Merge pull request #5 from SantaRiver/develop

Refactor frontend structure and enhance deployment workflows

Author: SantaRiver

.env.example

@@ -1,9 +1,10 @@
+# Reference template.
+# Use `.env.local.example` for local development
+# and `.env.server.example` for server deployment.
 POSTGRES_USER=santa
 POSTGRES_PASSWORD=santa_pass
 POSTGRES_DB=santagym
-BOT_TOKEN=YOUR_BOT_TOKEN_HERE
-JWT_SECRET=generate_strong_secret_key_here
-# В прод окружении тут будет реальный домен
-WEBHOOK_URL=https://api.santagym.local/api/v1/webhook
-
-FRONTEND_URL=https://gym.santariver.lol
+JWT_SECRET=change_me
+FRONTEND_URL=http://localhost:5173
+ALLOW_TEST_AUTH=false
+DEBUG=false

.env.local.example

@@ -0,0 +1,9 @@
+POSTGRES_USER=santa
+POSTGRES_PASSWORD=santa_pass
+POSTGRES_DB=santagym
+JWT_SECRET=local-dev-secret
+ALLOW_TEST_AUTH=true
+FRONTEND_URL=http://localhost:5173
+DEBUG=true
+CHOKIDAR_USEPOLLING=true
+WATCHPACK_POLLING=true

.env.server.example

@@ -0,0 +1,12 @@
+POSTGRES_USER=santa
+POSTGRES_PASSWORD=change_me
+POSTGRES_DB=santagym
+JWT_SECRET=change_me
+BOT_TOKEN=telegram_prod_bot_token
+WEBAPP_BASE_URL=https://gym.example.com
+WEBHOOK_URL=https://api.gym.example.com/api/v1/webhook
+FRONTEND_URL=https://gym.example.com
+FRONTEND_HOST=gym.example.com
+API_HOST=api.gym.example.com
+TRAEFIK_ACME_EMAIL=admin@example.com
+DEBUG=false

.github/workflows/ci.yml

@@ -93,6 +93,12 @@ jobs:
       - name: Validate docker compose config
         run: docker compose config
 
+      - name: Validate local compose config
+        run: docker compose --env-file .env.local.example -f docker-compose.yml -f docker-compose.local.yml config
+
+      - name: Validate server compose config
+        run: docker compose --env-file .env.server.example -f docker-compose.yml -f docker-compose.server.yml config
+
       - name: Build backend image
         run: docker build -f backend/Dockerfile backend
 

.github/workflows/deploy.yml

@@ -32,7 +32,7 @@ jobs:
           host: ${{ secrets.HOST }}
           username: ${{ secrets.USERNAME }}
           key: ${{ secrets.SSH_KEY }}
-          source: "backend,frontend,docker-compose.yml,.env.example"
+          source: "backend,frontend,docker-compose.yml,docker-compose.server.yml,.env.server.example"
           target: "/opt/santagym"
           rm: false
 
@@ -45,18 +45,18 @@ jobs:
           script: |
             set -euo pipefail
             cd /opt/santagym
-            if [ ! -f .env ]; then
-              cp .env.example .env
-              echo "Missing /opt/santagym/.env. Filled it from .env.example; update secrets before next deploy."
+            if [ ! -f .env.server ]; then
+              cp .env.server.example .env.server
+              echo "Missing /opt/santagym/.env.server. Filled it from .env.server.example; update secrets before next deploy."
             fi
 
-            docker compose build backend bot frontend
-            docker compose up -d db redis traefik
-            docker compose run --rm backend alembic upgrade head
-            docker compose up -d backend bot frontend
+            docker compose --env-file .env.server -f docker-compose.yml -f docker-compose.server.yml build backend bot frontend
+            docker compose --env-file .env.server -f docker-compose.yml -f docker-compose.server.yml up -d db redis traefik
+            docker compose --env-file .env.server -f docker-compose.yml -f docker-compose.server.yml run --rm backend alembic upgrade head
+            docker compose --env-file .env.server -f docker-compose.yml -f docker-compose.server.yml up -d backend bot frontend
 
-            timeout 120 sh -c 'until docker compose exec -T backend python -c "import urllib.request; urllib.request.urlopen(\"http://127.0.0.1:8000/health\")"; do sleep 5; done'
-            timeout 120 sh -c 'until docker compose exec -T frontend wget --no-verbose --tries=1 --spider http://127.0.0.1/; do sleep 5; done'
+            timeout 120 sh -c 'until docker compose --env-file .env.server -f docker-compose.yml -f docker-compose.server.yml exec -T backend python -c "import urllib.request; urllib.request.urlopen(\"http://127.0.0.1:8000/health\")"; do sleep 5; done'
+            timeout 120 sh -c 'until docker compose --env-file .env.server -f docker-compose.yml -f docker-compose.server.yml exec -T frontend wget --no-verbose --tries=1 --spider http://127.0.0.1/; do sleep 5; done'
 
-            docker compose ps
+            docker compose --env-file .env.server -f docker-compose.yml -f docker-compose.server.yml ps
             docker image prune -af

.gitignore

@@ -21,6 +21,7 @@ Icon
 .env
 .env.production
 .env.local
+.env.server
 *.pem
 *.key
 .claude/

Makefile

@@ -0,0 +1,21 @@
+LOCAL_COMPOSE=docker compose --env-file .env.local -f docker-compose.yml -f docker-compose.local.yml
+SERVER_COMPOSE=docker compose --env-file .env.server -f docker-compose.yml -f docker-compose.server.yml
+
+local-up:
+	$(LOCAL_COMPOSE) up --build -d db redis backend frontend
+
+local-down:
+	$(LOCAL_COMPOSE) down
+
+local-logs:
+	$(LOCAL_COMPOSE) logs -f backend frontend db redis
+
+local-migrate:
+	$(LOCAL_COMPOSE) exec backend alembic upgrade head
+
+local-init:
+	$(LOCAL_COMPOSE) up --build -d db redis backend
+	$(LOCAL_COMPOSE) exec backend alembic upgrade head
+
+server-config:
+	$(SERVER_COMPOSE) config

README.md

@@ -60,90 +60,105 @@ SantaGymBot/
 
 ---
 
-## 🚀 Локальная разработка
+## 🚀 Local Development
 
 ### Требования
 * Docker & Docker Compose
-* Node.js (v20+)
-* Python 3.12+ / Poetry (Опционально, если запускать бэк без докера)
+* GNU Make
+* Node.js / Python локально не обязательны, если используете только Docker
 
 ### 1. Подготовка окружения
-Клонируйте репозиторий и создайте файл секретов окружения:
+Клонируйте репозиторий и создайте local env:
 ```bash
 git clone <repository_url>
 cd SantaGymBot
-cp .env.example .env
+cp .env.local.example .env.local
 ```
 
-Отредактируйте `.env`:
-* Обязательно укажите `BOT_TOKEN` (получив его у @BotFather в Telegram).
-* Сгенерируйте `JWT_SECRET` (любая длинная случайная строка).
-
-### 2. Запуск Backend + Инфраструктура
-Мы используем Docker для поднятия Базы данных (PostgreSQL), Кэша (Redis) и самого Бэкенда (API + Bot).
+### 2. Первый запуск
 
 ```bash
-docker compose up -d --build
+make local-init
+make local-up
 ```
-> **Внимание:** В локальном режиме бэкенд будет доступен Траефиком по хосту `api.santagym.local` (если прописать его в `/etc/hosts` локальной машины), либо можно маппить порты `8000:8000` напрямую для тестов.
 
-### 3. Накатываем миграции Базы Данных
-Чтобы в БД появились таблицы, необходимо применить миграции Alembic:
+Локальный стенд поднимает:
+- `db`
+- `redis`
+- `backend`
+- `frontend`
 
-```bash
-docker compose exec backend alembic upgrade head
-```
+`bot` в обычный local workflow не входит.
+
+### 3. Адреса сервисов
+
+- API: `http://localhost:8000`
+- Frontend: `http://localhost:5173`
+
+### 4. Миграции
 
-*(Если вы модифицировали модели и нужно создать новую миграцию):*
 ```bash
-docker compose exec backend alembic revision --autogenerate -m "reason"
-docker compose exec backend alembic upgrade head
+make local-migrate
 ```
 
-### 4. Запуск Frontend
-В отдельном окне терминала перейдите в папку `frontend`:
+### 5. Логи и остановка
 
 ```bash
-cd frontend
-npm install
-npm run dev
+make local-logs
+make local-down
 ```
-Фронтенд запустится на `http://localhost:5173`.
-> **Для справки:** При тестировании фронта локально (в браузере, а не внутри Telegram), инициализация будет проходить через заглушку (bypass auth), создавая "тестового пользователя", чтобы вы могли разрабатывать UI без подключения дебаггера смартфона.
+
+### 6. Local Auth
+
+Локальная разработка использует controlled fallback auth через `test_mode`, если в `.env.local` включен `ALLOW_TEST_AUTH=true`.
+
+Это подходит для:
+- UI разработки
+- локальной проверки API
+- быстрой отладки в браузере
+
+Это не заменяет реальную проверку Telegram WebApp авторизации.
+
+Детали: [local-stand.md](/Users/santa/PycharmProjects/SantaGymBot/docs/ops/local-stand.md:1)
 
 ---
 
-## 🌍 Production Деплой (Развертывание на сервер)
+## 🌍 Server Deployment
+
+Серверный режим использует отдельный compose override с `Traefik`, `bot` и production-oriented frontend runtime.
 
-Проект спроектирован так, чтобы его можно было безболезненно развернуть на VPS (Ubuntu/Debian) без лишних конфликтов портов благодаря использованию сетки Traefik.
+### 1. Подготовка env
 
-### 1. Настройка домена
-Направьте A-запись вашего домена (например, `gymbot.example.com` и `api.gymbot.example.com`) на IP вашего сервера.
+```bash
+cp .env.server.example .env.server
+```
+
+Заполните как минимум:
+- `BOT_TOKEN`
+- `JWT_SECRET`
+- `WEBAPP_BASE_URL`
+- `WEBHOOK_URL`
+- `FRONTEND_HOST`
+- `API_HOST`
+- `TRAEFIK_ACME_EMAIL`
+
+### 2. Проверка server topology
 
-### 2. Подготовка .env для PROD
-В файле `.env` на сервере:
 ```dotenv
-WEBHOOK_URL=https://api.gymbot.example.com/api/v1/webhook
-JWT_SECRET=super_strong_production_key...
-POSTGRES_PASSWORD=super_strong_password
-...
+make server-config
 ```
 
-### 3. Изменение Traefik-конфигурации (docker-compose)
-В prod-окружении необходимо:
-1. Заменить `--api.insecure=true` на SSL/Let's Encrypt Entrypoints в настройках `traefik`.
-2. Добавить метки (labels) для `frontend` контейнера (напишите prod-dockerfile, который собирает статику и отдает через `nginx`). Либо отдавать статику через CDN.
-3. Обновить label хоста бэкенда:
-   ```yaml
-   - "traefik.http.routers.backend.rule=Host(`api.gymbot.example.com`)"
-   ```
+### 3. Запуск server stack
 
-### 4. Запуск и миграция
 ```bash
-docker compose up -d --build
-docker compose exec backend alembic upgrade head
+docker compose --env-file .env.server -f docker-compose.yml -f docker-compose.server.yml up -d --build
+docker compose --env-file .env.server -f docker-compose.yml -f docker-compose.server.yml exec backend alembic upgrade head
 ```
 
+`Traefik` здесь нужен для host-based routing и размещения нескольких ботов/WebApp на одном сервере без конфликта внешних портов `80/443`.
+
+Детали: [server-stand.md](/Users/santa/PycharmProjects/SantaGymBot/docs/ops/server-stand.md:1)
+
 ---
 
 ## 🔒 Модель безопасности
@@ -163,7 +178,7 @@ docker compose exec backend alembic upgrade head
 
 ## Deployment (GitHub Actions)
 
-This project has CI/CD configured using GitHub Actions. Upon pushing to the `main` branch, the code is copied via SCP and started using docker-compose on the target server.
+This project has CI/CD configured using GitHub Actions. The pipeline validates frontend, backend and compose configuration. Deployment uses the server compose topology.
 
 ### Setup Server Secrets
 Navigate to **Settings > Secrets and variables > Actions** in your GitHub repository and add:
@@ -172,13 +187,13 @@ Navigate to **Settings > Secrets and variables > Actions** in your GitHub reposi
 - `SSH_KEY`: The private Ed25519 or RSA SSH key to access the VPS
 
 ### Initial Server Setup
-Make sure the folder exists and create a `.env` file containing the protected API tokens:
+Make sure the folder exists and create a `.env.server` file containing the protected runtime secrets:
 ```bash
 # Connect to your server
 ssh root@YOUR_SERVER_IP
 mkdir -p /opt/santagym
 cd /opt/santagym
-nano .env
+nano .env.server
 ```
 
-Fill the `.env` with your variables (`BOT_TOKEN`, `POSTGRES_USER`, etc).
+Fill `.env.server` with your variables (`BOT_TOKEN`, `POSTGRES_USER`, `WEBAPP_BASE_URL`, etc).

backend/Dockerfile.local

@@ -0,0 +1,13 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+RUN pip install --no-cache-dir poetry
+
+COPY pyproject.toml poetry.lock* ./
+RUN poetry config virtualenvs.create false \
+    && poetry install --no-interaction --no-ansi --no-root
+
+COPY . .
+
+CMD ["uvicorn", "app.main_api:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

backend/app/application/services/auth_service.py

@@ -3,14 +3,15 @@
 import hashlib
 from urllib.parse import parse_qsl
 from datetime import datetime, timedelta
+
 import jwt
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.config import settings
 from app.infrastructure.database.repositories.user import user_repo
 
 class AuthService:
-    def __init__(self, bot_token: str, jwt_secret: str):
+    def __init__(self, bot_token: str | None, jwt_secret: str):
         self.bot_token = bot_token
         self.jwt_secret = jwt_secret
 
@@ -19,6 +20,9 @@ def validate_telegram_data(self, init_data: str) -> dict:
         Провалидировать initData от Telegram WebApp.
         Возвращает распаршенный JSON пользователя или кидает ValueError.
         """
+        if not self.bot_token:
+            raise ValueError("BOT_TOKEN is not configured")
+
         parsed_data = dict(parse_qsl(init_data))
         if "hash" not in parsed_data:
             raise ValueError("No hash in init_data")