docs: add details to env.example

.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

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 админке.
 

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`, и перейдите в админ-панель.

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` / админка | Ключ темы по умолчанию. |

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 скрывается.