mnemo_cards/docs/coolify-migration.md

Coolify: перенос сервисов (backend Docker, web статик, внешняя БД)

Цель: перенести существующие сервисы в Coolify (через Traefik/Let’s Encrypt), сохранив БД на хосте. Ниже — пошаговая инструкция, Dockerfile-примеры, настройки Coolify и порядок переключения трафика.

1. Backend (Dart) в Docker

Структура образа

• Base (builder): dart:stable-sdk
• Runtime: debian:bookworm-slim (или distroless)
• Порт: 8081
• Health: GET /health (замените, если другой endpoint)

Пример Dockerfile

# stage: build
FROM dart:stable-sdk AS builder
WORKDIR /app
COPY pubspec.* ./
RUN dart pub get
COPY . .
RUN dart compile exe lib/main.dart -o /app/server

# stage: runtime
FROM debian:bookworm-slim
WORKDIR /app
COPY --from=builder /app/server /app/server
EXPOSE 8081
CMD ["/app/server", "-a", "0.0.0.0", "-p", "8081"]

Env для внешней БД (БД остаётся на хосте)

• DB_HOST — IP хоста (обычно 172.17.0.1 или реальный публичный/приватный IP)
• DB_PORT — порт вашей БД
• DB_NAME, DB_USER, DB_PASSWORD
• Если нужен TLS к БД: добавить флаги клиента/сертификаты

Настройка сети/Traefik

• В сервисе (compose) добавить:

networks:
  - coolify
extra_hosts:
  - "host.docker.internal:host-gateway"

• Traefik (через Coolify UI → Domains):
  • Domain: api.mnemo-cards.online
  • EntryPoints: websecure
  • Cert resolver: le
  • HTTP→HTTPS редирект уже есть через middleware redirectscheme

Шаги в Coolify (UI)

1. Project → Environment → New Service → Dockerfile.
2. Указать репозиторий/ветку и путь к Dockerfile.
3. Env: DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD (+ ваши APP_*).
4. Network: подключить coolify.
5. Domains: api.mnemo-cards.online, entrypoint websecure, resolver le.
6. Healthcheck: HTTP 200 на /health (или ваш путь).

2. Web и Admin (Flutter Web) как статика в контейнере

Сборка

flutter build web --release \
  --dart-define=API_BASE_URL=https://api.mnemo-cards.online

Артефакт: build/web/.

Пример Dockerfile (nginx)

FROM nginx:1.27-alpine
COPY build/web/ /usr/share/nginx/html/
RUN rm /etc/nginx/conf.d/default.conf
COPY default.conf /etc/nginx/conf.d/default.conf
EXPOSE 80

default.conf:

server {
  listen 80;
  server_name _;
  root /usr/share/nginx/html;
  index index.html;
  location / {
    try_files $uri $uri/ /index.html;
  }
  location /assets/ {
    try_files $uri =404;
    add_header Cache-Control "public, max-age=31536000, immutable";
  }
}

Разделение сервисов

• Web: домен mnemo-cards.online
• Admin: домен admin.mnemo-cards.online Рекомендуется два сервиса в Coolify (два образа или один образ + разные домены).

Шаги в Coolify

1. New Service → Dockerfile/Image (web).
2. Network: coolify.
3. Domains:
   • web: mnemo-cards.online → entrypoint websecure, resolver le.
   • admin: admin.mnemo-cards.online (отдельный сервис либо второй домен).
4. Healthcheck: HEAD / (200/301/302).

3. Traefik/LE (уже поднят)

• Порты 80/443 заняты Traefik.
• Все сервисы должны быть в сети coolify.
• Для каждого домена в Coolify задать entrypoint websecure и resolver le; HTTP→HTTPS редирект активен.

4. Порядок миграции/катовера

1. Собрать и запушить образы:
   • backend (Dart) → registry.
   • web/admin статика → отдельные образы.
2. Создать сервисы в Coolify (backend, web, admin) c env и доменами.
3. Протестировать:
   • Временно через hosts или временный домен (Coolify supports additional domain).
   • Проверить доступ к БД из контейнера (psql/curl).
4. Подключить боевые домены:
   • api.mnemo-cards.online, mnemo-cards.online, admin.mnemo-cards.online.
5. Переключить трафик:
   • Остановить legacy systemd backend и nginx, когда новые сервисы отвечают.
6. Мониторинг/откат:
   • При проблемах: стартануть старый systemd/nginx (бэкап конфигов: /root/pre-coolify-backup-2025-12-07.tar.gz).

5. Проверки после миграции

• HTTPS: curl -I https://api.mnemo-cards.online, https://mnemo-cards.online, https://admin.mnemo-cards.online → 200/301/302, валидный LE.
• Health: все сервисы green в Coolify; backend /health 200.
• БД: приложение читает/пишет (прогнать базовый сценарий).
• Логи: нет ошибок подключения к БД/Redis.
• Сеть: наружу открыты только 80/443 (Traefik); внутренние порты не публиковать.

6. Что остаётся на хосте

• База данных остаётся на сервере; контейнеры подключаются как к внешнему ресурсу (DB_HOST = IP хоста).
• Traefik/LE уже работают в Docker, используется resolver le.