pjandro/3x-ui
1
0
Fork 0
mirror of https://github.com/MHSanaei/3x-ui.git synced 2026-07-26 09:52:14 +03:00
Code Issues Packages Projects Releases Wiki Activity

v3

Sanaei
2026-06-03 00:39:58 +02:00
parent 204fb51286
commit 44d5e58907
1 changed files with 93 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
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://<your-ip>:<your-port>` 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://<your-ip>:<your-port>/<your-path>` 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://<your-ip>: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://<your-ip>: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 <container_id>
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 <container_id>
@@ -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
```
```
> [!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.