diff --git a/Installation.md b/Installation.md index 30d377f..7b328d0 100644 --- a/Installation.md +++ b/Installation.md @@ -1,12 +1,12 @@ ## Install in one-line (recommended) 1. Install the necessary tools to run the script: `curl` (if needed) -2. Open shell and enter this command +2. Open a shell and enter this command: ```bash bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) ``` -3. Go through the panel setup -4. Once configured, go to `http://:` and log in with the credentials that were issued by the panel after installation +3. Go through the panel setup. The installer generates a **random username, password, and web base path** for you. +4. Once configured, go to `http://:/` and log in with the credentials issued by the panel after installation. Run `x-ui` at any time to reopen the management menu (start/stop the service, view or reset credentials, manage SSL certificates, and more). ## Docker @@ -20,40 +20,75 @@ bash <(curl -sSL https://get.docker.com) ### Using Docker Compose -3. Create a `panel` folder and go to this folder +3. Create a `panel` folder and go to it ```bash mkdir panel cd panel ``` -4. Create and edit the `compose.yml` file using `nano` or another editor. Insert the following contents into the file: +4. Create and edit the `docker-compose.yml` file using `nano` or another editor. Insert the following contents: -`compose.yml` +`docker-compose.yml` ```yml services: 3xui: image: ghcr.io/mhsanaei/3x-ui:latest container_name: 3xui_app # hostname: yourhostname <- optional + # The bundled Fail2ban (XUI_ENABLE_FAIL2BAN below) enforces the per-client IP + # limit with iptables, which needs NET_ADMIN. Without these caps a ban is + # logged and shown in fail2ban status but never actually applied. + # NET_RAW covers ip6tables. If you disable Fail2ban you can drop cap_add. + cap_add: + - NET_ADMIN + - NET_RAW volumes: - $PWD/db/:/etc/x-ui/ - $PWD/cert/:/root/cert/ environment: XRAY_VMESS_AEAD_FORCED: "false" XUI_ENABLE_FAIL2BAN: "true" + # To use PostgreSQL instead of the default SQLite, run: + # docker compose --profile postgres up -d + # and uncomment the two lines below. + # XUI_DB_TYPE: "postgres" + # XUI_DB_DSN: "postgres://xui:xui@postgres:5432/xui?sslmode=disable" tty: true - network_mode: host + ports: + - "2053:2053" + restart: unless-stopped + + # Optional PostgreSQL backend — only started with: docker compose --profile postgres up -d + postgres: + image: postgres:16-alpine + container_name: 3xui_postgres + profiles: ["postgres"] + environment: + POSTGRES_USER: xui + POSTGRES_PASSWORD: xui + POSTGRES_DB: xui + volumes: + - $PWD/pgdata/:/var/lib/postgresql/data restart: unless-stopped ``` -5. Start the Docker container using the following command. +> [!TIP] +> The `ports` block only publishes the panel port (`2053`). Your inbound (proxy) ports are **not** exposed automatically — add each one to the `ports` list, or replace the `ports` block with `network_mode: host` to expose every port the panel opens. + +5. Start the container: ```bash docker compose up -d ``` -6. Open url `http://:2053` and log in to the panel. The credentials are as follows: +To use the bundled PostgreSQL backend instead of SQLite, uncomment the two `XUI_DB_*` lines above and start with the profile: + +```bash +docker compose --profile postgres up -d +``` + +6. Open `http://:2053` and log in to the panel. The default credentials are: - 👤 Username: `admin` - 🔑 Password: `admin` @@ -62,11 +97,11 @@ docker compose up -d > After logging in, **immediately** change the administrator credentials in the panel settings (`Panel Settings > Authentication`) > [!TIP] -> It is also recommended to set up two-factor authentication and set up another panel web path for complete security +> It is also recommended to set up two-factor authentication and configure a custom panel web path for complete security #### Update -If an update is needed, disable the container and push the new version of the image with the following commands +If an update is needed, stop the container and pull the new image: ```bash docker compose down @@ -76,7 +111,7 @@ docker compose up -d #### Delete -If you want to delete a container, execute the following commands +If you want to delete the container, execute: ```bash docker compose down @@ -86,7 +121,7 @@ rm panel -rf ### Using CLI -3. Execute the following command +3. Execute the following command: ```bash docker run -itd \ @@ -94,32 +129,37 @@ docker run -itd \ -e XUI_ENABLE_FAIL2BAN=true \ -v $PWD/db/:/etc/x-ui/ \ -v $PWD/cert/:/root/cert/ \ + --cap-add=NET_ADMIN \ + --cap-add=NET_RAW \ --network=host \ --restart=unless-stopped \ --name 3x-ui \ ghcr.io/mhsanaei/3x-ui:latest ``` +> [!NOTE] +> `--cap-add=NET_ADMIN --cap-add=NET_RAW` are required for the bundled Fail2ban to enforce per-client IP limits with iptables. `--network=host` exposes every port the panel opens (panel + all inbounds); to publish ports individually instead, drop `--network=host` and add `-p 2053:2053` plus one `-p` per inbound port. + #### Update -If an update is needed, disable the container and push the new version of the image with the following commands +To update, find the container ID, stop it, and pull the new image: ```bash docker ps -a ``` -With this command, we find out the ID of the container on which the panel is running. Next, we stop our container and pull down the image: +With this command, we find out the ID of the container the panel is running on. Next, stop the container and pull the image: ```bash docker container stop docker image pull ghcr.io/mhsanaei/3x-ui ``` -After that, we execute the command from step 3. +After that, run the command from step 3 again. #### Delete -If you want to delete a container, execute the following commands +If you want to delete the container, execute: ```bash docker container stop @@ -131,14 +171,14 @@ rm 3x-ui -rf 3. Install the `git` package using your package manager. -4. Clone repository and go to repository folder +4. Clone the repository and go to its folder: ```bash git clone https://github.com/MHSanaei/3x-ui.git cd 3x-ui ``` -5. Start the Docker container using the following command. In this case, the Docker image will be built first and then the container will be started. +5. Start the container with the command below. The repository's `docker-compose.yml` builds the image from source first and then starts the container: ```bash docker compose up -d @@ -151,14 +191,14 @@ docker compose up -d 1. Install the necessary tools to run the script: `curl` (if needed) -2. Open shell and enter this command +2. Open a shell and enter this command: ```bash VERSION=v2.5.5 && bash <(curl -Ls "https://raw.githubusercontent.com/mhsanaei/3x-ui/$VERSION/install.sh") $VERSION ``` The required version is specified in the `VERSION` variable, e.g. `v2.5.5`. -3. Go through the panel setup +3. Go through the panel setup. ## Manual installation @@ -180,7 +220,7 @@ esac wget https://github.com/MHSanaei/3x-ui/releases/latest/download/x-ui-linux-${XUI_ARCH}.tar.gz ``` -Once the compressed package is downloaded, execute the following commands to install or upgrade x-ui +Once the compressed package is downloaded, execute the following commands to install or upgrade x-ui: ```bash ARCH=$(uname -m) @@ -213,27 +253,43 @@ tar zxvf x-ui-linux-${XUI_ARCH}.tar.gz chmod +x x-ui/x-ui x-ui/bin/xray-linux-* x-ui/x-ui.sh cp x-ui/x-ui.sh /usr/bin/x-ui -# Copy appropriate service file based on OS +# Copy the appropriate service file based on OS if [ -f "x-ui/x-ui.service" ]; then cp -f x-ui/x-ui.service /etc/systemd/system/ -elif [[ "$release" == "ubuntu" || "$release" == "debian" || "$release" == "armbian" ]]; then - if [ -f "x-ui/x-ui.service.debian" ]; then - cp -f x-ui/x-ui.service.debian /etc/systemd/system/x-ui.service - else - echo "Service file not found in archive, downloading..." - curl -fLo /etc/systemd/system/x-ui.service https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.service.debian - fi else - if [ -f "x-ui/x-ui.service.rhel" ]; then - cp -f x-ui/x-ui.service.rhel /etc/systemd/system/x-ui.service - else - echo "Service file not found in archive, downloading..." - curl -fLo /etc/systemd/system/x-ui.service https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.service.rhel - fi + case "${release}" in + ubuntu | debian | armbian) + if [ -f "x-ui/x-ui.service.debian" ]; then + cp -f x-ui/x-ui.service.debian /etc/systemd/system/x-ui.service + else + echo "Service file not found in archive, downloading..." + curl -fLo /etc/systemd/system/x-ui.service https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.service.debian + fi + ;; + arch | manjaro | parch) + if [ -f "x-ui/x-ui.service.arch" ]; then + cp -f x-ui/x-ui.service.arch /etc/systemd/system/x-ui.service + else + echo "Service file not found in archive, downloading..." + curl -fLo /etc/systemd/system/x-ui.service https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.service.arch + fi + ;; + *) + if [ -f "x-ui/x-ui.service.rhel" ]; then + cp -f x-ui/x-ui.service.rhel /etc/systemd/system/x-ui.service + else + echo "Service file not found in archive, downloading..." + curl -fLo /etc/systemd/system/x-ui.service https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.service.rhel + fi + ;; + esac fi mv x-ui/ /usr/local/ systemctl daemon-reload systemctl enable x-ui systemctl restart x-ui -``` \ No newline at end of file +``` + +> [!NOTE] +> Alpine Linux uses OpenRC instead of systemd, so the systemd steps above don't apply. Use the one-line installer on Alpine, which sets up an OpenRC service automatically.