From 204bf97cec1ebbe530a554a7047587501887bfb3 Mon Sep 17 00:00:00 2001 From: Krr0ptioN Date: Tue, 30 Jul 2024 12:22:37 +0300 Subject: [PATCH] docs: migrating existing documents to docs.marzneshin.org --- content/docs/configuration/marzneshin.md | 78 +++++ content/docs/contribution-guideline/api.md | 7 + .../docs/contribution-guideline/support.md | 16 + .../installation/marzneshin.md | 159 +++++++++ content/docs/how-to-guides/backup.md | 17 + content/docs/how-to-guides/marzneshin-cli.md | 311 ++++++++++++++++++ content/docs/how-to-guides/telegram-bot.md | 13 + content/docs/how-to-guides/webhook.md | 28 ++ 8 files changed, 629 insertions(+) create mode 100644 content/docs/contribution-guideline/api.md create mode 100644 content/docs/how-to-guides/marzneshin-cli.md create mode 100644 content/docs/how-to-guides/telegram-bot.md diff --git a/content/docs/configuration/marzneshin.md b/content/docs/configuration/marzneshin.md index 2533d79..c26464c 100644 --- a/content/docs/configuration/marzneshin.md +++ b/content/docs/configuration/marzneshin.md @@ -1,3 +1,81 @@ --- title: Marzneshin --- + +> You can set settings below using environment variables or placing them in `.env` file. + +## Basic + +| Variable | Description | +| ------------------------------- | ----------------------------------------------------------------------------------------------------- | +| UVICORN_HOST | Bind application to this host (default: `0.0.0.0`) | +| UVICORN_PORT | Bind application to this port (default: `8000`) | +| UVICORN_UDS | Bind application to a UNIX domain socket | +| UVICORN_SSL_CERTFILE | SSL certificate file to have application on https | +| UVICORN_SSL_KEYFILE | SSL key file to have application on https | +| SQLALCHEMY_DATABASE_URL | Database URL ([SQLAlchemy's docs](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls)) | +| JWT_ACCESS_TOKEN_EXPIRE_MINUTES | Expire time for the Access Tokens in minutes, `0` considered as infinite (default: `1440`) | + +## Subscription and VPN customization + +| Variable | Description | +| --------------------------- | -------------------------------------------------------------------------------------------- | +| CUSTOM_TEMPLATES_DIRECTORY | Customized templates directory (default: `app/templates`) | +| CLASH_SUBSCRIPTION_TEMPLATE | The template that will be used for generating clash configs (default: `clash/default.yml`) | +| SUBSCRIPTION_PAGE_TEMPLATE | The template used for generating subscription info page (default: `subscription/index.html`) | +| SUBSCRIPTION_URL_PREFIX | Prefix of subscription URLs | +| HOME_PAGE_TEMPLATE | Decoy page template (default: `home/index.html`) | + +## Telegram + +| Variable | Description | +| ------------------ | -------------------------------------------------------------------------------------------- | +| TELEGRAM_API_TOKEN | Telegram bot API token (get token from [@botfather](https://t.me/botfather)) | +| TELEGRAM_ADMIN_ID | Numeric Telegram ID of admin (use [@userinfobot](https://t.me/userinfobot) to found your ID) | +| TELEGRAM_PROXY_URL | Run Telegram Bot over proxy | + +## Notification & Webhook + +| Variable | Description | +| --------------------------------- | ----------------------------------------------------------------------------------------------------- | +| WEBHOOK_ADDRESS | Webhook address to send notifications to. Webhook notifications will be sent if this value was set. | +| WEBHOOK_SECRET | Webhook secret will be sent with each request as `x-webhook-secret` in the header (default: `None`) | +| NUMBER_OF_RECURRENT_NOTIFICATIONS | How many times to retry if an error detected in sending a notification (default: `3`) | +| RECURRENT_NOTIFICATIONS_TIMEOUT | Timeout between each retry if an error detected in sending a notification in seconds (default: `180`) | +| NOTIFY_REACHED_USAGE_PERCENT | At which percentage of usage to send the warning notification (default: `80`) | +| NOTIFY_DAYS_LEFT | When to send warning notification about expiration (default: `3`) | + +## Development and Documentation + +| Variable | Description | +| -------- | ------------------------------------------------------------------------------------------- | +| DOCS | Whether API documents should be available on `/docs` and `/redoc` or not (default: `False`) | +| DEBUG | Debug mode for development (default: `False`) | + +## .env File Example + +```sh +SQLALCHEMY_DATABASE_URL= +UVICORN_HOST= +UVICORN_PORT= +UVICORN_UDS= +UVICORN_SSL_CERTFILE= +UVICORN_SSL_KEYFILE= +SUBSCRIPTION_URL_PREFIX= +CUSTOM_TEMPLATES_DIRECTORY= +CLASH_SUBSCRIPTION_TEMPLATE= +SUBSCRIPTION_PAGE_TEMPLATE= +HOME_PAGE_TEMPLATE= +TELEGRAM_API_TOKEN= +TELEGRAM_ADMIN_ID= +TELEGRAM_PROXY_URL= +JWT_ACCESS_TOKEN_EXPIRE_MINUTES= +DOCS=true +DEBUG=true +WEBHOOK_ADDRESS="http://localhost:9000" +WEBHOOK_SECRET="dont-tell-anybody" +NUMBER_OF_RECURRENT_NOTIFICATIONS= +RECURRENT_NOTIFICATIONS_TIMEOUT= +NOTIFY_REACHED_USAGE_PERCENT= +NOTIFY_DAYS_LEFT= +``` diff --git a/content/docs/contribution-guideline/api.md b/content/docs/contribution-guideline/api.md new file mode 100644 index 0000000..bb41d6b --- /dev/null +++ b/content/docs/contribution-guideline/api.md @@ -0,0 +1,7 @@ +--- +title: "API" +--- + +Marzneshin provides a REST API that enables developers to interact with Marzneshin +services programmatically. To view the API documentation in Swagger UI or ReDoc, set +the configuration variable `DOCS=True` and navigate to the `/docs` and `/redoc`. diff --git a/content/docs/contribution-guideline/support.md b/content/docs/contribution-guideline/support.md index e69de29..5817bce 100644 --- a/content/docs/contribution-guideline/support.md +++ b/content/docs/contribution-guideline/support.md @@ -0,0 +1,16 @@ +--- +title: "Support" +--- + +# Donation + +If you found Marzneshin useful and would like to support its development, you can make a donation in one of the +following crypto networks: + +- Bitcoin network: 13ZDhE5KHGsfjM4A22eLTUgW98WpXhQTuF +- TRON network (TRC20): TYxFCiRqJ3SiV6rAQAmJUd3DgVmJvEAfz4 +- TON network: EQB_VYiU73U1_wk-01I_MLg9-hx953VOf9Y36t2Z04WyUapD + +Part of the donations would be tipped to contributors, the rest to collaborators. + +May developers be rich. diff --git a/content/docs/getting-started/installation/marzneshin.md b/content/docs/getting-started/installation/marzneshin.md index 1ab5151..0955f9b 100644 --- a/content/docs/getting-started/installation/marzneshin.md +++ b/content/docs/getting-started/installation/marzneshin.md @@ -2,3 +2,162 @@ title: Installing Marzneshin weight: 1 --- + +Run the following command + +```bash +sudo bash -c "$(curl -sL https://github.com/khodedawsh/Marzneshin/raw/master/script.sh)" @ install +``` + +To install with mariadb: + +```bash +sudo bash -c "$(curl -sL https://github.com/khodedawsh/Marzneshin/raw/master/script.sh)" @ install --database mariadb +``` + +You could also use mysql by writing mysql instead, however mariadb is **recommended**. +Also to install the latest nightly release use the `--nightly` option. + +Once the installation is complete: + +- You'd notice the logs, which you could stop watching by pressing `Ctrl+C`; The process will continue running normally. +- the configuration file can be found at `/etc/opt/marzneshin/.env` (refer to [configurations](#configuration) section + to see variables) +- Data files will be placed at `/var/lib/marzneshin`; e.g. the sqlite database. +- You can access the Marzneshin dashboard by opening a web browser and navigating + to `http://:8000/dashboard/` + +Next, you need to create a sudo admin for logging into the Marzneshin dashboard by the following command + +```bash +marzneshin cli admin create --sudo +``` + +That's it! You can login to your dashboard using these credentials + +To see the help message of the Marzneshin script, run the following command + +```bash +marzneshin --help +``` + +If you are eager to run the project using the source code, check the section below + +
+

Manual install (advanced)

 + +Clone this project and install the dependencies (you'd need Python >= 3.10) + +```bash +git clone https://github.com/khodedawsh/Marzneshin +cd Marzneshin/ +wget -qO- https://bootstrap.pypa.io/get-pip.py | python3 - +python3 -m pip install -r requirements.txt +``` + +Alternatively, to have an isolated environment you can use [Python Virtualenv](https://pypi.org/project/virtualenv/) + +To install dashboard dependencies and build the dashboard: + +```bash +make dashboard-deps +make dashboard-build +``` + +note that you'll need pnpm and npm installed. + +If you want to use `marzneshin-cli`, you should link it to a file in your `$PATH`, make it executable, and install the +auto-completion: + +```bash +sudo ln -s $(pwd)/marzneshin-cli.py /usr/bin/marzneshin-cli +sudo chmod +x /usr/bin/marzneshin-cli +marzneshin-cli completion install +``` + +Now it's time to configuration + +Make a copy of `.env.example` file, take a look and edit it using a text editor like `nano`. + +```bash +cp .env.example .env +nano .env +``` + +> Check [marzneshin configuration](docs/configuration/marzneshin) guide for more information + +Eventually, launch the application using command below + +```bash +make start +``` + +To launch with linux systemctl (copy marzneshin.service file to `/var/lib/marzneshin/marzneshin.service`) + +``` +systemctl enable /var/lib/marzneshin/marzneshin.service +systemctl start marzneshin +``` + +To use with nginx + +``` +server { + listen 443 ssl http2; + listen [::]:443 ssl http2; + server_name example.com; + + ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; + + location ~* /(dashboard|static|locales|api|docs|redoc|openapi.json) { + proxy_pass http://0.0.0.0:8000; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + } + + # xray-core ws-path: / + # client ws-path: /marzneshin/me/2087 + # + # All traffic is proxed through port 443, and send to the xray port(2087, 2088 etc.). + # The '/marzneshin' in location regex path can changed any characters by yourself. + # + # /${path}/${username}/${xray-port} + location ~* /marzneshin/.+/(.+)$ { + proxy_redirect off; + proxy_pass http://127.0.0.1:$1/; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_set_header Host $http_host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + } +} +``` + +or + +``` +server { + listen 443 ssl http2; + listen [::]:443 ssl http2; + server_name marzneshin.example.com; + + ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; + + location / { + proxy_pass http://0.0.0.0:8000; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + } +} +``` + +By default the app will be run on `http://localhost:8000/dashboard`. You can configure it using changing +the `UVICORN_HOST` and `UVICORN_PORT` environment variables. + +
diff --git a/content/docs/how-to-guides/backup.md b/content/docs/how-to-guides/backup.md index e69de29..1cbda62 100644 --- a/content/docs/how-to-guides/backup.md +++ b/content/docs/how-to-guides/backup.md @@ -0,0 +1,17 @@ +--- +title: "Backup" +--- + +It's always a good idea to backup your Marzneshin files regularly to prevent data loss in case of system failures or +accidental deletion. Here are the steps to backup Marzneshin: + +1. By default, all Marzneshin important files are saved in `/var/lib/marzneshin` (Docker versions). Copy the + entire `/var/lib/marzneshin` directory to a backup location of your choice, such as an external hard drive or cloud + storage. +2. Additionally, make sure to backup your env file, which contains your configuration variables. If you installed + Marzneshin using the script (recommended installation approach), the env and other configurations should be + inside `/etc/opt/marzneshin/` directory. + +By following these steps, you can ensure that you have a backup of all your Marzneshin files and data, as well as your +configuration variables and Xray configuration, in case you need to restore them in the future. Remember to update your +backups regularly to keep them up-to-date. diff --git a/content/docs/how-to-guides/marzneshin-cli.md b/content/docs/how-to-guides/marzneshin-cli.md new file mode 100644 index 0000000..9dde226 --- /dev/null +++ b/content/docs/how-to-guides/marzneshin-cli.md @@ -0,0 +1,311 @@ +--- +title: "Marzneshin CLI" +--- + +Marzneshin comes with an integrated CLI named `marzneshin-cli` which allows administrators to have direct interaction +with it. + +If you've installed Marzneshin using the installation script, you can access the cli commands by running + +```bash +marzneshin cli [OPTIONS] COMMAND [ARGS]... +``` + +**Usage**: + +```console +[OPTIONS] COMMAND [ARGS]... +``` + +**Options**: + +- `--help`: Show this message and exit. + +**Commands**: + +- `admin` +- `completion`: Generate and install completion scripts. +- `subscription` +- `user` + +## `admin` + +**Usage**: + +```console +admin [OPTIONS] COMMAND [ARGS]... +``` + +**Options**: + +- `--help`: Show this message and exit. + +**Commands**: + +- `create`: Creates an admin +- `delete`: Deletes the specified admin +- `import-from-env`: Imports the sudo admin from env +- `list`: Displays a table of admins +- `update`: Updates the specified admin + +### `admin create` + +Creates an admin + +Password can also be set using the `MARZBAN_ADMIN_PASSWORD` environment variable for non-interactive usages. + +**Usage**: + +```console +admin create [OPTIONS] +``` + +**Options**: + +- `-u, --username TEXT`: [required] +- `--sudo / --no-sudo` +- `--help`: Show this message and exit. + +### `admin delete` + +Deletes the specified admin + +Confirmations can be skipped using `--yes/-y` option. + +**Usage**: + +```console +admin delete [OPTIONS] +``` + +**Options**: + +- `-u, --username TEXT`: [required] +- `-y, --yes`: Skips confirmations +- `--help`: Show this message and exit. + +### `admin import-from-env` + +Imports the sudo admin from env + +Confirmations can be skipped using `--yes/-y` option. + +What does it do? + +- Creates a sudo admin according to `SUDO_USERNAME` and `SUDO_PASSWORD`. +- Links any user which doesn't have an `admin_id` to the imported sudo admin. + +**Usage**: + +```console +admin import-from-env [OPTIONS] +``` + +**Options**: + +- `-y, --yes`: Skips confirmations +- `--help`: Show this message and exit. + +### `admin list` + +Displays a table of admins + +**Usage**: + +```console +admin list [OPTIONS] +``` + +**Options**: + +- `-o, --offset INTEGER` +- `-l, --limit INTEGER` +- `-u, --username TEXT`: Search by username +- `--help`: Show this message and exit. + +### `admin update` + +Updates the specified admin + +NOTE: This command CAN NOT be used non-interactively. + +**Usage**: + +```console +admin update [OPTIONS] +``` + +**Options**: + +- `-u, --username TEXT`: [required] +- `--help`: Show this message and exit. + +## `completion` + +Generate and install completion scripts. + +**Usage**: + +```console +completion [OPTIONS] COMMAND [ARGS]... +``` + +**Options**: + +- `--help`: Show this message and exit. + +**Commands**: + +- `install`: Install completion for the specified shell. +- `show`: Show completion for the specified shell,... + +### `completion install` + +Install completion for the specified shell. + +**Usage**: + +```console +completion install [OPTIONS] [SHELL]:[bash|zsh|fish|powershell|pwsh] +``` + +**Arguments**: + +- `[SHELL]:[bash|zsh|fish|powershell|pwsh]`: The shell to install completion for. + +**Options**: + +- `--help`: Show this message and exit. + +### `completion show` + +Show completion for the specified shell, to copy or customize it. + +**Usage**: + +```console +completion show [OPTIONS] [SHELL]:[bash|zsh|fish|powershell|pwsh] +``` + +**Arguments**: + +- `[SHELL]:[bash|zsh|fish|powershell|pwsh]`: The shell to install completion for. + +**Options**: + +- `--help`: Show this message and exit. + +## `subscription` + +**Usage**: + +```console +subscription [OPTIONS] COMMAND [ARGS]... +``` + +**Options**: + +- `--help`: Show this message and exit. + +**Commands**: + +- `get-config`: Generates a subscription config. +- `get-link`: Prints the given user's subscription link. + +### `subscription get-config` + +Generates a subscription config. + +Generates a subscription config for the given user in the given format. + +The output will be written in the output file when the `output-file` is present, +otherwise will be shown in the terminal. + +**Usage**: + +```console +subscription get-config [OPTIONS] +``` + +**Options**: + +- `-u, --username TEXT`: [required] +- `-f, --format [v2ray|clash]`: [required] +- `-o, --output TEXT`: Writes the generated config in the file if provided +- `--base64`: Encodes output in base64 format if present +- `--help`: Show this message and exit. + +### `subscription get-link` + +Prints the given user's subscription link. + +NOTE: This command needs `XRAY_SUBSCRIPTION_URL_PREFIX` environment variable to be set +in order to work correctly. + +**Usage**: + +```console +subscription get-link [OPTIONS] +``` + +**Options**: + +- `-u, --username TEXT`: [required] +- `--help`: Show this message and exit. + +## `user` + +**Usage**: + +```console +user [OPTIONS] COMMAND [ARGS]... +``` + +**Options**: + +- `--help`: Show this message and exit. + +**Commands**: + +- `list`: Displays a table of users +- `set-owner`: Transfers user's ownership + +### `user list` + +Displays a table of users + +NOTE: Sorting is not currently available. + +**Usage**: + +```console +user list [OPTIONS] +``` + +**Options**: + +- `-o, --offset INTEGER` +- `-l, --limit INTEGER` +- `-u, --username TEXT`: Search by username +- `--status [active|disabled|limited|expired]` +- `--admin, --owner TEXT`: Search by owner admin's username +- `--help`: Show this message and exit. + +### `user set-owner` + +Transfers user's ownership + +NOTE: This command needs additional confirmation for users who already have an owner. + +**Usage**: + +```console +user set-owner [OPTIONS] +``` + +**Options**: + +- `-u, --username TEXT` +- `--admin, --owner TEXT`: Admin's username +- `-y, --yes`: Skips confirmations +- `--help`: Show this message and exit. diff --git a/content/docs/how-to-guides/telegram-bot.md b/content/docs/how-to-guides/telegram-bot.md new file mode 100644 index 0000000..5116bba --- /dev/null +++ b/content/docs/how-to-guides/telegram-bot.md @@ -0,0 +1,13 @@ +--- +title: "Telegram Bot" +--- + +Marzneshin comes with an integrated Telegram bot that can handle server management, user creation and removal, and send +notifications. This bot can be easily enabled by following a few simple steps, and it provides a convenient way to +interact with Marzneshin without having to log in to the server every time. + +To enable Telegram Bot: + +1. set `TELEGRAM_API_TOKEN` to your bot's API Token +2. set `TELEGRAM_ADMIN_ID` to your Telegram account's numeric ID, you can get your ID + from [@userinfobot](https://t.me/userinfobot) diff --git a/content/docs/how-to-guides/webhook.md b/content/docs/how-to-guides/webhook.md index e69de29..c62699f 100644 --- a/content/docs/how-to-guides/webhook.md +++ b/content/docs/how-to-guides/webhook.md @@ -0,0 +1,28 @@ +--- +title: "Webhook notifications" +--- + +You can set a webhook address and Marzneshin will send the notifications to that address. + +the requests will be sent as a post request to the address provided by `WEBHOOK_ADDRESS` with `WEBHOOK_SECRET` +as `x-webhook-secret` in the headers. + +Example request sent from Marzneshin: + +``` +Headers: +Host: 0.0.0.0:9000 +User-Agent: python-requests/2.28.1 +Accept-Encoding: gzip, deflate +Accept: */* +Connection: keep-alive +x-webhook-secret: something-very-very-secret +Content-Length: 107 +Content-Type: application/json + +Body: +{"username": "marzneshin_test_user", "action": "user_updated", "enqueued_at": 1680506457.636369, "tries": 0} +``` + +Different action typs +are: `user_created`, `user_updated`, `user_deleted`, `user_limited`, `user_expired`, `user_disabled`, `user_enabled`