mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-07-16 01:26:07 +00:00
MHSanaei
9b91f0f42e
Fold the standalone 3x-ui-docs project (Next.js 16 + Fumadocs, deployed to docs.sanaei.dev) into docs/ so the panel and its documentation share a single source of truth, the way sing-box keeps its docs in-tree. The old repo becomes redundant and can be retired. - Import the full site under docs/ (app, components, content, lib, public, scripts, config). The self-contained pnpm project sits alongside the existing engineering notes with no filename collisions. - Re-point "Edit on GitHub" links from MHSanaei/3x-ui-docs to this repo's docs/content/docs path (docs/lib/shared.ts, docs/app/.../page.tsx). - Add docs-ci.yml and docs-deploy.yml under .github/workflows/, scoped to docs/** and run with working-directory: docs, since GitHub only runs workflows from the repo-root .github/. deploy-static.yml's GitHub Pages publish (CNAME docs.sanaei.dev) carries over unchanged. Follow-up (outside this commit): attach the docs.sanaei.dev custom domain to this repository's Pages (or set the Vercel project's root directory to docs), confirm the site is live from the monorepo, then delete MHSanaei/3x-ui-docs.
149 lines
4.5 KiB
Plaintext
149 lines
4.5 KiB
Plaintext
---
|
|
title: Installation
|
|
description: Install 3x-ui via the official script (stable, pinned, or dev-latest), unattended/cloud-init, or Docker — and choose SQLite or PostgreSQL.
|
|
icon: Download
|
|
---
|
|
|
|
3x-ui runs on a wide range of Linux distributions — Ubuntu, Debian, Armbian,
|
|
Fedora, CentOS, RHEL, AlmaLinux, Rocky Linux, Oracle Linux, Amazon Linux,
|
|
Virtuozzo, Arch, Manjaro, openSUSE (Tumbleweed/Leap), Alpine — and Windows,
|
|
across `amd64`, `386`, `arm64`, `armv7`, `armv6`, `armv5`, and `s390x`.
|
|
|
|
<Callout type="warn">
|
|
Run the script installer as **root** (or with `sudo`). It installs a service,
|
|
sets up the `x-ui` management command, and enables the panel on boot.
|
|
</Callout>
|
|
|
|
<Tabs items={['Script', 'Docker', 'Manual']}>
|
|
|
|
<Tab value="Script">
|
|
|
|
The official script is the recommended path. During installation it generates a
|
|
**random** username, password, and access (web base) path, sets up the service,
|
|
and installs the `x-ui` management command.
|
|
|
|
```bash title="latest stable"
|
|
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
|
|
```
|
|
|
|
Install a **specific version** by appending its tag:
|
|
|
|
```bash title="pinned version"
|
|
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) v3.4.0
|
|
```
|
|
|
|
Install the rolling **dev** build (the latest per-commit pre-release from `main`
|
|
— not a stable release) by passing `dev-latest`:
|
|
|
|
```bash title="rolling dev build"
|
|
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) dev-latest
|
|
```
|
|
|
|
When it finishes, note the printed login details and run `x-ui` to open the
|
|
[management menu](/docs/guide/update-uninstall#the-x-ui-management-menu), then
|
|
continue to [First login](/docs/guide/first-login).
|
|
|
|
</Tab>
|
|
|
|
<Tab value="Docker">
|
|
|
|
The default Compose setup uses SQLite. Clone the repo (or copy its
|
|
`docker-compose.yml` and `Dockerfile`) and start it:
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
To run with the bundled **PostgreSQL** service, uncomment the two `XUI_DB_*`
|
|
lines in `docker-compose.yml` and start with the profile:
|
|
|
|
```bash
|
|
docker compose --profile postgres up -d
|
|
```
|
|
|
|
Prefer the prebuilt image? It's published to the GitHub Container Registry. The
|
|
image bundles Fail2ban (for [IP limits](/docs/operations/security)), which bans
|
|
with `iptables` and therefore needs `NET_ADMIN` (and `NET_RAW` for IPv6) —
|
|
otherwise bans are logged but never applied:
|
|
|
|
```bash title="docker run"
|
|
docker run -d \
|
|
--cap-add=NET_ADMIN \
|
|
--cap-add=NET_RAW \
|
|
-e XUI_ENABLE_FAIL2BAN=true \
|
|
-v $PWD/db/:/etc/x-ui/ \
|
|
-v $PWD/cert/:/root/cert/ \
|
|
--network=host \
|
|
--restart=unless-stopped \
|
|
--name 3x-ui \
|
|
ghcr.io/mhsanaei/3x-ui:latest
|
|
```
|
|
|
|
The `db/` volume holds the SQLite database (`/etc/x-ui/x-ui.db`) and `cert/`
|
|
holds TLS certificates, so your data survives upgrades.
|
|
|
|
</Tab>
|
|
|
|
<Tab value="Manual">
|
|
|
|
For advanced users, download a release archive for your architecture from the
|
|
[releases page](https://github.com/MHSanaei/3x-ui/releases), extract it, and run
|
|
the binary as a systemd service. The install script automates exactly these
|
|
steps, so it's preferred unless you have a specific reason to install by hand.
|
|
|
|
</Tab>
|
|
|
|
</Tabs>
|
|
|
|
## Build your install command
|
|
|
|
Tailor the command to your setup:
|
|
|
|
<InstallCommandBuilder />
|
|
|
|
## Choose a database
|
|
|
|
You pick the storage backend at install time:
|
|
|
|
- **SQLite** (default) — a single file at `/etc/x-ui/x-ui.db`. Zero setup.
|
|
- **PostgreSQL** — for high client counts or multi-node setups. The installer
|
|
can install it locally or use a DSN you provide.
|
|
|
|
See [Database](/docs/reference/database) for details and SQLite→PostgreSQL
|
|
migration.
|
|
|
|
## Unattended / cloud-init
|
|
|
|
The installer also runs **non-interactively** for automation. Set
|
|
`XUI_NONINTERACTIVE=1` (or run with no TTY) and it installs end-to-end with zero
|
|
prompts, generating random credentials and writing them to
|
|
`/etc/x-ui/install-result.env`:
|
|
|
|
```bash
|
|
XUI_NONINTERACTIVE=1 bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
|
|
```
|
|
|
|
The repo's [`deploy/`](https://github.com/MHSanaei/3x-ui/tree/main/deploy)
|
|
directory has ready-made **cloud-init** user-data for unattended installs on any
|
|
cloud (Hetzner, AWS, DigitalOcean, Vultr, GCP, Azure, Oracle).
|
|
|
|
## Next steps
|
|
|
|
<Cards>
|
|
<Card
|
|
title="First login"
|
|
href="/docs/guide/first-login"
|
|
description="Reach the panel and secure it."
|
|
/>
|
|
<Card
|
|
title="Update & uninstall"
|
|
href="/docs/guide/update-uninstall"
|
|
description="The x-ui menu, updates, and removal."
|
|
/>
|
|
<Card
|
|
title="REALITY"
|
|
href="/docs/config/reality"
|
|
description="Configure your first stealthy inbound."
|
|
/>
|
|
</Cards>
|