x-ui/CONTRIBUTING.md

Contribution guide

This document describes development-only setup options for contributing to the x-ui project. Production deployments are out of scope for this guide.

For safety, Docker-based development is strongly recommended.
Local installation should be performed only inside a VM or disposable environment.

---

Recommended: Docker development setup

Prerequisites

• Docker
• Docker Compose (v2+)
• Git

Steps

git clone https://github.com/alireza0/x-ui.git
# or:
# git clone https://github.com/<your_fork_name>/x-ui.git

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

Explore panel

• Panel should be available at localhost:54321 like: http://127.0.0.1:54321 for example
• Default credentials: admin / admin

To stop and remove containers or ctrl + C:

docker compose down

Environment

When using the Docker development setup, the docker-compose.dev.yml file mounts the local database directory into the container:

volumes:
  - ./dev/db:/etc/x-ui

This means:

• ./dev/db on the host is used to persist panel state during development
• /etc/x-ui inside the container is the active database/config directory
• Data will survive container restarts but is isolated from the host system
• You can safely delete ./dev/db to reset the development database

---

Local development setup (unsafe on host OS)

This method runs scripts with root privileges and alters the host system. Use only inside a VM, container, or disposable test environment.

Prerequisites

• Ubuntu/Debian or Fedora (actually anything with systemd, just use proper package manager)

Install dependencies

# Ubuntu / Debian
sudo apt update
sudo apt upgrade -y
sudo apt install -y golang unzip git wget

# Fedora
sudo dnf update -y
sudo dnf install -y golang unzip git wget

Setup panel

git clone https://github.com/alireza0/x-ui.git
# or:
# git clone https://github.com/<your_fork_name>/x-ui.git

cd x-ui/
sudo bash x-ui.sh   # Select -> 10. Start

Explore panel

• Panel should be available at localhost:54321 like: http://127.0.0.1:54321 for example
• Default credentials: admin / admin