From f69f6546f0d6fcdd39e01d95dece18cc4ad8c3b0 Mon Sep 17 00:00:00 2001 From: 3252a8 <3252a8@proton.me> Date: Thu, 21 May 2026 11:39:07 +0300 Subject: [PATCH] docs: add details to env.example --- .env.example | 53 +++++++++++++++++++++++++++++++++++++------ README.md | 3 ++- docs/configuration.md | 13 ++++++++++- docs/env-vars.md | 5 ++-- docs/webapp.md | 4 ++++ 5 files changed, 67 insertions(+), 11 deletions(-) diff --git a/.env.example b/.env.example index c99ed41..1a0be7b 100644 --- a/.env.example +++ b/.env.example @@ -3,31 +3,70 @@ # Admin -> System -> Settings, Admin -> System -> Tariffs, Admin -> Appearance. # Full reference: docs/env-vars.md -# Required before first start +# Telegram bot token from @BotFather. +# Example: 1234567890:AA... BOT_TOKEN=your_bot_token_here + +# Telegram numeric user IDs allowed to open the admin panel. +# Use commas for several admins, for example: 123456789,987654321 ADMIN_IDS=123456789 + +# Public HTTPS base URL of the backend webhook server. +# Telegram, payment providers and Remnawave call webhook endpoints under this domain. +# This is usually the backend/API domain, not the Mini App frontend domain. +# Example: https://bot.yourdomain.tld WEBHOOK_BASE_URL=https://webhooks.yourdomain.tld -# PostgreSQL used by Docker Compose and backend +# PostgreSQL user created by Docker Compose and used by the backend. POSTGRES_USER=remnawave_minishop + +# PostgreSQL password. Change it before production deploy. POSTGRES_PASSWORD=change_me + +# PostgreSQL database name created by Docker Compose. POSTGRES_DB=remnawave_minishop -# Strongly recommended stable secrets. +# Enables the Web App and the Web App admin panel. +# Keep True for the first setup. If set to False, the admin UI is unavailable +# until you change it back to True in .env and restart the app. +WEBAPP_ENABLED=True + +# Stable secret for Web App sessions. # Generate with: openssl rand -hex 32 +# If empty, sessions are invalidated on every restart. WEBAPP_SESSION_SECRET= + +# Stable Telegram webhook secret_token. +# Generate with: openssl rand -hex 32 +# If empty, a new token can be generated on process start. WEBHOOK_SECRET_TOKEN= -# Recommended baseline values. -# Remnawave access stays in .env, but can be overridden from the Web App admin. +# Public HTTPS URL of the Mini App frontend, with trailing slash. +# This URL is opened by Telegram buttons and BotFather Mini App settings. +# Do not put /api or webhook paths here. +# Example: https://app.yourdomain.tld/ SUBSCRIPTION_MINI_APP_URL=https://app.yourdomain.tld/ + +# Remnawave panel API URL. Usually the panel domain plus /api. +# Example: https://panel.yourdomain.tld/api PANEL_API_URL=https://panel.yourdomain.tld/api + +# Remnawave API key with permissions to manage users, subscriptions and squads. +# Keep this secret. It can be overridden later in the admin panel if needed. PANEL_API_KEY= + +# Shared secret for validating incoming Remnawave webhooks. +# Use the same value when configuring the webhook in Remnawave panel. PANEL_WEBHOOK_SECRET= -# Optional host ports for local Compose publication. +# Host port that publishes the backend webhook server from Docker Compose. +# Your reverse proxy should route WEBHOOK_BASE_URL traffic to this port. WEB_SERVER_PORT=8080 + +# Host port that publishes the frontend nginx from Docker Compose. +# Your reverse proxy should route SUBSCRIPTION_MINI_APP_URL traffic to this port. FRONTEND_PORT=8082 -# Optional reverse proxy trust list for X-Forwarded-For. +# Reverse proxy IPs/CIDRs trusted for X-Forwarded-For. +# Keep loopback for local proxy; add your proxy network if needed. TRUSTED_PROXIES=127.0.0.1,::1 diff --git a/README.md b/README.md index 96e7d6e..b0147d2 100644 --- a/README.md +++ b/README.md @@ -80,8 +80,9 @@ docker compose logs -f backend worker frontend - `ADMIN_IDS` - Telegram ID администраторов через запятую; - `WEBHOOK_BASE_URL` - публичный URL вебхуков; - `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` - доступы PostgreSQL; +- `WEBAPP_ENABLED=True` - включает Web App и админку для первого входа; - `WEBAPP_SESSION_SECRET`, `WEBHOOK_SECRET_TOKEN` - стабильные секреты; -- `SUBSCRIPTION_MINI_APP_URL` - публичный URL Mini App; +- `SUBSCRIPTION_MINI_APP_URL` - публичный HTTPS URL Mini App/frontend, например `https://app.domain.com/`; - `PANEL_API_URL`, `PANEL_API_KEY`, `PANEL_WEBHOOK_SECRET` - доступ к Remnawave; - остальные настройки удобнее задать в Web App админке. diff --git a/docs/configuration.md b/docs/configuration.md index 0ce80e2..93eabc0 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -26,9 +26,10 @@ nano .env | `ADMIN_IDS` | Telegram ID администраторов через запятую; без этого не попасть в Web App админку. | | `WEBHOOK_BASE_URL` | Публичный URL webhook-домена backend. | | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` | Доступы PostgreSQL для Compose и backend. | +| `WEBAPP_ENABLED` | Включает Web App и админку. Для первого запуска держите `True`. | | `WEBAPP_SESSION_SECRET` | Стабильный секрет сессий Web App. | | `WEBHOOK_SECRET_TOKEN` | Стабильный secret token Telegram webhook. | -| `SUBSCRIPTION_MINI_APP_URL` | Публичный URL Mini App, чтобы бот мог открыть личный кабинет. | +| `SUBSCRIPTION_MINI_APP_URL` | Публичный HTTPS URL Mini App/frontend, например `https://app.domain.com/`. Это URL, который открывают кнопки Telegram и который указывается в BotFather; не добавляйте сюда `/api` или webhook-пути. | | `PANEL_API_URL`, `PANEL_API_KEY`, `PANEL_WEBHOOK_SECRET` | Базовая интеграция с Remnawave. Эти значения стоит хранить в `.env`, но при необходимости их можно переопределить из админки. | `WEBAPP_SESSION_SECRET` и `WEBHOOK_SECRET_TOKEN` можно сгенерировать так: @@ -39,6 +40,16 @@ openssl rand -hex 32 Если оставить эти секреты пустыми, приложение сгенерирует их на процесс, но после рестарта Web App-сессии станут невалидными, а Telegram webhook получит новый `secret_token`. +## Если Web App выключен + +`WEBAPP_ENABLED=False` отключает пользовательский Web App и вместе с ним админ-панель. В таком состоянии нельзя зайти в **Система -> Настройки** и включить Web App обратно через UI. + +Чтобы восстановить доступ: + +1. В `.env` выставьте `WEBAPP_ENABLED=True`. +2. Перезапустите backend/frontend контейнеры, например `docker compose up -d --force-recreate backend frontend`. +3. Откройте `SUBSCRIPTION_MINI_APP_URL` под Telegram-аккаунтом из `ADMIN_IDS` и при необходимости проверьте настройку в админке. + ## Настройка через админку После запуска откройте Mini App под аккаунтом, чей Telegram ID указан в `ADMIN_IDS`, и перейдите в админ-панель. diff --git a/docs/env-vars.md b/docs/env-vars.md index d635712..467a2be 100644 --- a/docs/env-vars.md +++ b/docs/env-vars.md @@ -18,6 +18,7 @@ | `POSTGRES_USER` | `.env` / Compose | Пользователь PostgreSQL. | | `POSTGRES_PASSWORD` | `.env` / Compose | Пароль PostgreSQL. | | `POSTGRES_DB` | `.env` / Compose | Имя базы PostgreSQL. | +| `WEBAPP_ENABLED` | `.env` / админка | Включает Web App и админку. Держите `True` для первого запуска; если выключить, вернуть доступ можно только через `.env` и рестарт. | | `WEBAPP_SESSION_SECRET` | `.env` | Стабильный HMAC-секрет сессий Web App. Если пустой, генерируется на процесс, но сессии сбросятся после рестарта. | | `WEBHOOK_SECRET_TOKEN` | `.env` | Секрет Telegram webhook. Если пустой, генерируется на процесс. | @@ -110,8 +111,8 @@ | Переменная | Где менять | Назначение | | --- | --- | --- | -| `WEBAPP_ENABLED` | Админка | Включает Web App. | -| `SUBSCRIPTION_MINI_APP_URL` | Админка | Публичный URL Mini App. | +| `WEBAPP_ENABLED` | `.env` / админка | Включает Web App. Если `False`, пользовательский Web App и админка недоступны до включения через `.env` и рестарта. | +| `SUBSCRIPTION_MINI_APP_URL` | `.env` / админка | Публичный HTTPS URL Mini App/frontend, например `https://app.domain.com/`. Используется в Telegram-кнопках, referral-ссылках, email-входе и BotFather Mini App settings. Не указывайте здесь `/api` или webhook-пути. | | `WEBAPP_TITLE` | Админка | Заголовок Web App. | | `WEBAPP_THEMES_DIR` | `.env` | Каталог кастомных тем. | | `WEBAPP_DEFAULT_THEME` | `.env` / админка | Ключ темы по умолчанию. | diff --git a/docs/webapp.md b/docs/webapp.md index 986b700..388dbbe 100644 --- a/docs/webapp.md +++ b/docs/webapp.md @@ -52,6 +52,10 @@ SUPPORT_TICKETS_ENABLED=True SUPPORT_TICKET_RATE_LIMIT_PER_HOUR=5 ``` +`SUBSCRIPTION_MINI_APP_URL` - это публичный HTTPS URL именно frontend/Mini App, обычно отдельный домен вроде `https://app.domain.com/`. Его указывают в BotFather в Mini Apps, а бот использует его для кнопок личного кабинета, referral-ссылок и email-входа. Не добавляйте в него `/api`, `/webhook` или путь конкретной страницы. + +Если `WEBAPP_ENABLED=False`, пользовательский Web App и админ-панель не регистрируются. Чтобы снова попасть в админку, включите `WEBAPP_ENABLED=True` в `.env` и перезапустите backend/frontend контейнеры. + Внешний вид настраивается в админке: раздел **Внешний вид** управляет логотипом, emoji-логотипом, accent-цветом, выбранной темой и масштабом логотипа. Кастомные темы читаются из `WEBAPP_THEMES_DIR`, а `WEBAPP_DEFAULT_THEME` может принудительно выбрать тему по ключу. Подробный контракт `theme.json`, CSS/asset-роуты и пайплайн создания темы описаны в [webapp-themes.md](webapp-themes.md). Если SMTP-настройки не заполнены, вход по email скрывается.