Deployment Overview of 3X-UI on Server¶

Prerequisites and Basic Requirements¶

The deployment requires a Linux server running either Ubuntu, Debian, or a RHEL-based distribution (such as CentOS or Rocky Linux). The system must have root privileges to install Docker and configure the network. The following ports must be accessible through the firewall:

• Port 22/tcp for SSH access.
• Port 80/tcp for HTTP traffic and SSL certificate validation.
• Port 443/tcp for HTTPS traffic.
• A custom internal port (defined as {{ internal_port }}) for the application backend.

File and Directory Structure¶

The application and its dependencies utilize the following directory structure on the host server:

• /root/3x-ui/: Contains the Docker Compose configuration file (compose.yml).
• /data/3x-ui/db/: Stores the application database files.
• /data/3x-ui/cert/: Reserved for certificate storage (mapped via Docker volume).
• /data/nginx/: Contains Nginx configuration files and environment variables.
• /data/nginx/user_conf.d/: Stores custom Nginx server block configurations.
• /data/nginx/nginx-certbot.env: Environment file for the Nginx and Certbot container.
• /etc/docker/daemon.json: Docker daemon configuration file.

Application Installation Process¶

The application is deployed using Docker Compose. The installation process involves setting up the Docker Engine, creating the necessary directory structure, and launching the containers.

1. Docker Engine Installation:

   • For Debian/Ubuntu systems, the Docker CE repository is added, and the following packages are installed: docker-ce, docker-ce-cli, containerd.io, docker-buildx-plugin, docker-compose-plugin, net-tools, and dnsutils.
   • For RHEL-based systems, the Docker CE repository is added, and the following packages are installed: docker-ce, docker-ce-cli, containerd.io, docker-buildx-plugin, docker-compose-plugin, net-tools, and bind-utils.
   • The Docker daemon is configured via /etc/docker/daemon.json and started as a systemd service.

2. Directory Creation:

   • The directories /data, /root/3x-ui, /data/3x-ui, /data/3x-ui/db, /data/3x-ui/cert, /data/nginx/, and /data/nginx/user_conf.d are created with root ownership.

3. Container Deployment:

   • A Docker Compose file is generated at /root/3x-ui/compose.yml.
   • The application is started using the command docker compose up -d executed from the /root/3x-ui directory.

Access Rights and Security¶

Firewall rules are configured to allow necessary traffic while blocking unauthorized access.

• UFW Configuration:
  • SSH (22/tcp) is allowed.
  • HTTP (80/tcp) is allowed.
  • HTTPS (443/tcp) is allowed.
• Firewalld Configuration:
  • The firewalld service is disabled and stopped on systems where it is present.
• Application Access Control:
  • The Nginx configuration enforces strict host validation. Requests not matching the specific domain {{ prefix }}{{ server_id }}.{{ zone }} are rejected with a 444 status code.
  • Default administrative credentials are set during the initial deployment:
    • Username: admin
    • Username: root
  • The application listens on the internal port {{ internal_port }} and is exposed externally via the Nginx reverse proxy on port 443.

Databases¶

The application uses a local file-based database stored within the Docker container.

• Storage Location: The database files are persisted in the host directory /data/3x-ui/db/.
• Mount Point: This directory is mounted to /etc/x-ui/ inside the 3x-ui container.
• Configuration: No external database connection strings are required; the application manages its data internally within the mounted volume.

Docker Containers and Their Deployment¶

The deployment consists of two primary containers managed by Docker Compose:

1. 3x-ui Container:

   • Image: ghcr.io/mhsanaei/3x-ui:latest
   • Container Name: 3x-ui
   • Hostname: 3x-ui
   • Volumes:
     • /data/3x-ui/db/ mounted to /etc/x-ui/
     • nginx_secrets mounted to /root/cert/
   • Environment: XRAY_VMESS_AEAD_FORCED is set to false.
   • Ports: Exposes {{ internal_port }} internally; port 443 is mapped in the compose file but handled by the Nginx container.
   • Restart Policy: unless-stopped.

2. Nginx Container:

   • Image: jonasal/nginx-certbot:latest
   • Container Name: nginx-certbot
   • Environment:
     • CERTBOT_EMAIL is set to [email protected].
     • Additional variables are loaded from /data/nginx/nginx-certbot.env.
   • Volumes:
     • nginx_secrets mounted to /etc/letsencrypt.
     • /data/nginx/user_conf.d mounted to /etc/nginx/user_conf.d.
   • Ports:
     • 80:80
     • {{ internal_port }}:{{ internal_port }}
   • Dependencies: Depends on the 3x-ui container.
   • Restart Policy: unless-stopped.

3. Docker Volumes:

   • A named volume nginx_secrets is created externally to store SSL certificates and secrets shared between the Nginx and 3x-ui containers.

Proxy Servers¶

Nginx acts as a reverse proxy and SSL terminator for the 3x-ui application.

• Configuration Location: Custom server blocks are stored in /data/nginx/user_conf.d/ with the filename format {{ prefix }}{{ server_id }}.{{ zone }}.conf.
• SSL Configuration:
  • Certificates are managed by the nginx-certbot container and stored in the nginx_secrets volume.
  • The Nginx configuration references certificates at /etc/letsencrypt/live/{{ prefix }}{{ server_id }}.{{ zone }}/.
  • SSL parameters include ssl_certificate, ssl_certificate_key, ssl_trusted_certificate, and ssl_dhparam.
• Proxy Settings:
  • Nginx listens on {{ internal_port }} with SSL and HTTP/2 enabled.
  • Traffic is proxied to the 3x-ui container at http://3x-ui:{{ internal_port }}.
  • Headers Host, X-Real-IP, X-Forwarded-For, Upgrade, and Connection are forwarded to the backend.
  • Proxy buffering is disabled (proxy_buffering off).
  • Timeouts are set to 5s for connection and 60s for read operations.

Permission Settings¶

File and directory permissions are set during the deployment process to ensure secure access:

• Directories:
  • /data, /root/3x-ui, /data/3x-ui, /data/3x-ui/db, /data/3x-ui/cert, /data/nginx/, and /data/nginx/user_conf.d are owned by root:root with mode 0640.
• Configuration Files:
  • /root/3x-ui/compose.yml is owned by root:root with mode 0644.
  • /data/nginx/user_conf.d/{{ prefix }}{{ server_id }}.{{ zone }}.conf is owned by root:root with mode 0644.
  • /data/nginx/nginx-certbot.env is owned by root:root with mode 0644.
  • /etc/docker/daemon.json is owned by root:root with mode 0644.

Starting, Stopping, and Updating¶

The application is managed via Docker Compose and Docker commands.

• Starting the Application:
  • Execute docker compose up -d from the /root/3x-ui directory.
• Restarting the Application:
  • Execute docker restart 3x-ui to restart the main application container.
• Updating the Application:
  • Pull the latest image using docker pull ghcr.io/mhsanaei/3x-ui:latest.
  • Recreate the containers using docker compose up -d.
• Service Management:
  • The Docker daemon service is managed via systemctl (e.g., systemctl status docker).
  • The application containers are managed via docker compose commands.