From 9b08f181a6b623012ba13795bb0199ac1e5b9e69 Mon Sep 17 00:00:00 2001
From: sigseg5 <sigseg5@protonmail.com>
Date: Fri, 6 Feb 2026 22:42:51 +0300
Subject: [PATCH] add contributing guideline with docker and local developer
 setup

---
 .gitignore             |  3 +-
 CONTRIBUTING.md        | 94 ++++++++++++++++++++++++++++++++++++++++++
 docker-compose.dev.yml | 15 +++++++
 3 files changed, 111 insertions(+), 1 deletion(-)
 create mode 100644 CONTRIBUTING.md
 create mode 100644 docker-compose.dev.yml

diff --git a/.gitignore b/.gitignore
index e0212345..09e120fc 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,4 +14,5 @@ dist/
 release/
 /release.sh
 /x-ui
-.DS_Store
\ No newline at end of file
+.DS_Store
+/dev/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..c07c30c4
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,94 @@
+# 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
+
+```bash
+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](http://127.0.0.1:54321) for example
+- Default credentials: `admin` / `admin`
+
+To stop and remove containers or `ctrl` + `C`:
+
+```bash
+docker compose down
+```
+
+### Environment
+
+When using the Docker development setup, the [docker-compose.dev.yml](/docker-compose.dev.yml) file mounts the local database directory into the container:
+
+```yaml
+volumes:
+  - ./dev/db:/etc/x-ui
+```
+
+This means:
+
+- [./dev/db](/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
+
+```bash
+# 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
+
+```bash
+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](http://127.0.0.1:54321) for example
+- Default credentials: `admin` / `admin`
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
new file mode 100644
index 00000000..4990c474
--- /dev/null
+++ b/docker-compose.dev.yml
@@ -0,0 +1,15 @@
+services:
+  xui:
+    build:
+      context: .
+      target: builder
+    working_dir: /app
+    volumes:
+      - .:/app
+      - ./dev/db:/etc/x-ui
+    environment:
+      XUI_BIN_FOLDER: /app/dev/bin
+      XUI_DB_FOLDER: /etc/x-ui
+      XUI_LOG_LEVEL: debug
+      XUI_DEBUG: "true"
+    command: ["go","run","./main.go"]