Deployment Overview of 3X-UI Graphics Panel on Server¶
Prerequisites and Basic Requirements¶
To ensure a successful deployment, the server must meet the following requirements:
-
Operating System: Ubuntu, Debian, CentOS, Rocky Linux, or AlmaLinux.
-
Privileges: Root or sudo access is required for all installation steps.
-
Network Ports:
-
22/tcp(SSH) -
80/tcp(HTTP/SSL Challenge) -
443/tcp(HTTPS) -
34171/tcp(Internal Application Port)
FQDN of the final panel on the hostkey.in domain¶
The application uses a specific subdomain template for access via HTTPS.
| Parameter | Value |
|---|---|
| Prefix | 3x-ui |
| Domain | hostkey.in |
| Full template | 3x-ui{Server_ID_from_Invapi}.hostkey.in |
File and Directory Structure¶
The application utilizes several directories for configuration, data persistence, and SSL certificates:
-
/root/3x-ui: Contains the Docker Compose deployment file. -
/data/3x-ui/db/: Stores the application database. -
/data/3x-ui/cert/: Stores application-specific certificate data. -
/data/nginx/user_conf.d/: Contains Nginx virtual host configurations. -
/data/nginx/letsencrypt/.well-known/acme-challenge/: Used for SSL certificate renewal challenges. -
/data/nginx/nginx-certbot.env: Environment configuration for the SSL container.
Application installation process¶
The installation follows a multi-step process to prepare the environment and deploy the application via Docker:
-
System Preparation: The system is updated, and necessary dependencies such as
ca-certificates,curl, andgnupgare installed. -
Docker Engine Installation:
-
For Debian/Ubuntu systems: The official Docker GPG key is fetched, the repository is added, and
docker-ce,docker-compose-plugin, and related tools are installed. -
For RHEL/CentOS/Rocky/AlmaLinux systems: The Docker CE repository is configured via
yumordnf, and the engine is installed. -
Kernel Optimization: TCP BBR (Bottleneck Bandwidth and Round-trip propagation time) is enabled to improve network performance.
-
Container Deployment: A
compose.ymlfile is generated in/root/3x-ui/and executed using Docker Compose to launch the application and its proxy. -
Application Configuration: The application's internal settings (username, password, and port) are configured via command-line interface commands within the running container.
Access Rights and Security¶
Security is managed through both system-level firewalls and container isolation:
-
Firewall Management:
-
On RHEL-based systems,
firewalldis disabled to prevent conflicts with Docker networking. -
On Debian/Ubuntu systems,
ufwis configured to allow SSH (22), HTTP (80), and HTTPS (443). -
User Access: The application's default credentials are updated during installation for both the
adminandrootusers. -
SSL Security: An Nginx container manages SSL certificates via Certbot, ensuring all traffic is encrypted over port 443.
Databases¶
The application uses an internal database for storing configuration and user data. The database files are persisted on the host machine at:
/data/3x-ui/db/
Docker Containers and Their Deployment¶
The deployment consists of two primary containers managed via a compose.yml file located in /root/3x-ui/:
3x-ui¶
-
Image:
ghcr.io/mhsanaei/3x-ui:latest -
Container Name:
3x-ui -
Ports:
-
Host
443maps to Container443. -
Internal port
34171is exposed for proxying. -
Volumes:
-
/data/3x-ui/db/\(\rightarrow\)/etc/x-ui/ -
nginx_secrets(Docker Volume) \(\rightarrow\)/root/cert/ -
Environment Variables:
XRAY_VMESS_AEAD_FORCED="false" -
Restart Policy:
unless-stopped
nginx-certbot¶
-
Image:
jonasal/nginx-certbot:latest -
Container Name:
nginx-certbot -
Ports:
-
Host
80\(\rightarrow\) Container80 -
Host
34171\(\rightarrow\) Container34171 -
Volumes:
-
nginx_secrets(Docker Volume) \(\rightarrow\)/etc/letsencrypt -
/data/nginx/user_conf.d\(\rightarrow\)/etc/nginx/user_conf.d -
/data/nginx/letsencrypt\(\rightarrow\)/var/www/letsencrypt -
Environment Variables:
[email protected], plus settings from/data/nginx/nginx-certbot.env. -
Restart Policy:
unless-stopped
Application Update Instructions¶
To update the 3x-ui application, navigate to the deployment directory and pull the latest images:
Location of configuration files and data¶
| Type | Path |
|---|---|
| Docker Compose File | /root/3x-ui/compose.yml |
| Nginx Configs | /data/nginx/user_conf.d/ |
| Application Database | /data/3x-ui/db/ |
| SSL Certificates | nginx_secrets (Docker Volume) |
Available ports for connection¶
-
HTTPS:
443(via Nginx proxy) -
HTTP:
80(for SSL challenges and redirection) -
Internal API/Panel:
34171
Starting and Stopping the application¶
The application is managed using Docker Compose.
To start the application:
To stop the application:
Proxy Servers¶
The deployment utilizes an Nginx container (nginx-certbot) acting as a reverse proxy. It performs the following functions:
-
SSL Termination: Handles HTTPS encryption for the domain
3x-ui{Server_ID_from_Invapi}.hostkey.in. -
Automatic SSL Renewal: Uses Certbot to manage and renew certificates automatically via the
.well-known/acme-challenge/path. -
HTTP Redirection: Automatically redirects all traffic from port 80 to port 443.
-
Reverse Proxying: Forwards secure requests to the
3x-uicontainer on internal port34171.