Deployment Overview of 3X-UI on Server¶

Prerequisites and Basic Requirements¶

The deployment environment requires the following operating systems and privileges:

• Operating System: Ubuntu or Debian (Debian-based) OR RHEL, CentOS, or Fedora (Red Hat-based).

• Privileges: Root access is required for Docker installation, configuration, and container management.

• Dependencies: The installation process automatically installs Docker CE, Docker Compose plugin, net-tools, dnsutils (Debian/Ubuntu), or bind-utils (RHEL-based), ca-certificates, curl, and gnupg.

Fully Qualified Domain Name (FQDN)¶

The final panel is accessible via the following Fully Qualified Domain Name on the hostkey.in domain. Replace <server_id> with the actual server identifier associated with the instance:

3x-ui<server_id>.hostkey.in:443

File and Directory Structure¶

The application utilizes the following directory structure on the host server for configuration, data storage, and certificates:

Application Installation Process¶

The application is deployed using Docker Compose. The installer performs the following steps:

1. Docker Installation: Installs Docker CE and the Docker Compose plugin based on the detected Linux distribution.

2. Directory Setup: Creates necessary directories for data persistence and configuration.

3. Container Orchestration: Deploys two containers: 3x-ui and nginx-certbot.

4. Configuration: Sets the initial administrator credentials and internal port via Docker exec commands.

Container Images:

• 3X-UI: ghcr.io/mhsanaei/3x-ui:latest

• Nginx: jonasal/nginx-certbot:latest

Docker Containers and Their Deployment¶

The system utilizes docker compose to manage the services. The primary orchestration file is located at /root/3x-ui/compose.yml.

Services Configuration¶

• 3x-ui:

  • Container Name: 3x-ui

  • Hostname: 3x-ui

  • Restart Policy: unless-stopped

  • Volume Mounts:

    • Host /data/3x-ui/db/ maps to container /etc/x-ui/ (Database and config).

    • Docker Volume nginx_secrets maps to container /root/cert/.

  • Environment Variable: XRAY_VMESS_AEAD_FORCED set to false.

  • Exposed Port: The internal port defined in the configuration (e.g., 34171) is exposed within the Docker network.

• nginx-certbot:

  • Container Name: nginx-certbot

  • Restart Policy: unless-stopped

  • Environment:

    • CERTBOT_EMAIL set to [email protected].

    • Loads environment variables from /data/nginx/nginx-certbot.env.

  • Volume Mounts:

    • Docker Volume nginx_secrets maps to /etc/letsencrypt.

    • Host /data/nginx/user_conf.d maps to /etc/nginx/user_conf.d.

  • Dependencies: Depends on the 3x-ui service.

  • Ports:

    • Host 80 maps to container 80 (HTTP).

    • Host internal port maps to container internal port (HTTPS).

Execution¶

The containers are started using the following command within the project directory:

docker compose up -d

Proxy Servers and SSL Configuration¶

The deployment includes a reverse proxy using the nginx-certbot container to handle SSL termination and traffic routing.

• Proxy Engine: Nginx

• SSL Management: Automated via Certbot (ACME protocol) integrated within the Nginx container.

• Configuration File: The specific server block configuration is stored at /data/nginx/user_conf.d/3x-ui<server_id>.hostkey.in.conf.

• Routing:

  • The Nginx server listens on the internal port (e.g., 34171) for HTTPS traffic.

  • Traffic is proxied to the 3x-ui container at http://3x-ui:<internal_port>.

  • Proxy headers (Host, X-Real-IP, X-Forwarded-For, Upgrade, Connection) are forwarded to the backend.

  • Proxy buffering is disabled (proxy_buffering off).

• Security: The configuration returns a 444 error code if the requested Host header does not match the expected FQDN.

Access Rights and Security¶

• Firewall Configuration:

  • Red Hat-based systems: The firewalld service is disabled and stopped.

  • Debian/Ubuntu systems: The ufw firewall is enabled with specific rules allowing:

    • SSH (Port 22/tcp)

    • HTTP (Port 80/tcp)

    • HTTPS (Port 443/tcp)

• User Access: The deployment script creates two administrator accounts within the 3x-ui application:

  • Username: admin

  • Username: root

  • Password: Set to the same value as the SSH password used during the installation process.

Available Ports for Connection¶

The following ports are utilized by the deployment:

Note: Port 34171 is configurable via the internal_port variable in the configuration data.

Starting, Stopping, and Updating¶

Service management is performed using Docker and Docker Compose commands. All operations must be executed from the /root/3x-ui directory or specifying the path to the compose file.

• Start Services:

  cd /root/3x-ui
  docker compose up -d
  

• Stop Services:

  cd /root/3x-ui
  docker compose down
  

• Restart Services:

  docker compose restart
  

• Update Images: To pull the latest versions of the ghcr.io/mhsanaei/3x-ui and jonasal/nginx-certbot images:

  cd /root/3x-ui
  docker compose pull
  

• Restart Specific Container:

  docker restart 3x-ui
  docker restart nginx-certbot
  

Application Configuration and Data Location¶

The primary configuration files are generated and stored in the following locations:

• Docker Compose: /root/3x-ui/compose.yml

• Nginx Server Configuration: /data/nginx/user_conf.d/3x-ui<server_id>.hostkey.in.conf

• Nginx Environment: /data/nginx/nginx-certbot.env

• Docker Daemon: /etc/docker/daemon.json

• Application Data: /data/3x-ui/db/ (Contains database files and settings).

• SSL Certificates: Managed internally via the nginx_secrets volume, accessible at /etc/letsencrypt within the Nginx container.