bsodfather/crank
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e3cd02aa7eb2b53646c73f3b3c5e4d38816e7ca1
crank/docs/deployment.md
T
a.tolmachev f1042877b2 docs: add deploy and staging smoke runbook
2026-04-07 12:36:32 +03:00

8.7 KiB
Raw Blame History

Deployment

1. Назначение документа

Этот документ фиксирует platform-agnostic модель деплоя проекта.

Он отвечает на вопросы:

  • какие deployment artifacts должны быть в репозитории;
  • как проект должен запускаться в production-like окружении;
  • как routing должен работать через reverse proxy;
  • что должен делать CD pipeline.

Документ не привязан к конкретному hypervisor, cloud provider, типу VM или домашней инфраструктуре.

Практический post-deploy smoke checklist вынесен отдельно в deploy-and-staging-smoke.md.

2. Базовая модель деплоя

Для MVP принимается контейнерная модель:

  • admin-api, mcp-server и ui упаковываются в контейнеры;
  • PostgreSQL запускается как отдельный контейнер;
  • сервисы запускаются через docker-compose;
  • перед приложением находится reverse proxy;
  • CI проверяет качество, CD доставляет и перезапускает сервисы.

3. Что должно быть в репозитории

В проекте должны существовать:

  • Dockerfile для apps/admin-api;
  • Dockerfile для apps/mcp-server;
  • Dockerfile для apps/ui или отдельный production build flow для UI;
  • docker-compose.yml;
  • .env.example;
  • .github/workflows/ci.yml;
  • .github/workflows/deploy.yml;
  • примеры reverse proxy конфигураций.

Рекомендуемое стартовое распределение портов:

  • ui -> 3000
  • admin-api -> 3001
  • mcp-server -> 3002

4. Production-like runtime состав

Минимальный набор сервисов:

  • ui
  • admin-api
  • mcp-server
  • postgres

Persistent data:

  • volume для postgres;
  • volume или bind mount для artifact storage.

5. Рекомендуемая routing model

Под одним доменом:

  • / -> ui
  • /api/admin/ -> admin-api
  • /mcp/ -> mcp-server

Это позволяет:

  • централизовать TLS;
  • не плодить поддомены без необходимости;
  • держать demo URL простым;
  • использовать один reverse proxy для UI, API и MCP.

6. Требования к reverse proxy

Reverse proxy должен обеспечивать:

  • TLS termination;
  • редирект HTTP -> HTTPS;
  • X-Forwarded-* headers;
  • отключение buffering для MCP endpoint;
  • увеличенные таймауты для долгих runtime-запросов;
  • корректную маршрутизацию UI, admin API и MCP.

Особенно для mcp-server важно:

  • proxy_buffering off;
  • proxy_request_buffering off;
  • длинный proxy_read_timeout.

7. Пример nginx

server {
    listen 80;
    server_name example.com;

    return 301 https://$host$request_uri;
}

server {
    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;

    client_max_body_size 25m;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_http_version 1.1;

    location / {
        proxy_pass http://ui:3000;
    }

    location /api/admin/ {
        proxy_pass http://admin-api:3001/;
    }

    location /mcp/ {
        proxy_pass http://mcp-server:3002/;
        proxy_buffering off;
        proxy_request_buffering off;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

8. Пример Traefik

services:
  ui:
    labels:
      - traefik.enable=true
      - traefik.http.routers.ui.rule=Host(`example.com`) && PathPrefix(`/`)
      - traefik.http.services.ui.loadbalancer.server.port=3000

  admin-api:
    labels:
      - traefik.enable=true
      - traefik.http.routers.admin.rule=Host(`example.com`) && PathPrefix(`/api/admin`)
      - traefik.http.services.admin.loadbalancer.server.port=3001

  mcp-server:
    labels:
      - traefik.enable=true
      - traefik.http.routers.mcp.rule=Host(`example.com`) && PathPrefix(`/mcp`)
      - traefik.http.services.mcp.loadbalancer.server.port=3002

Для production нужно отдельно проверить timeout behavior на MCP маршруте.

9. Требования к docker-compose

docker-compose.yml должен:

  • поднимать postgres, admin-api, mcp-server, ui;
  • использовать env vars вместо hardcoded config;
  • иметь persistent storage для БД и artifacts;
  • поддерживать настраиваемый bind host для published ports;
  • публиковать ui, admin-api и mcp-server на loopback, если reverse proxy живет на том же хосте;
  • публиковать ui, admin-api и mcp-server на LAN bind address или 0.0.0.0, если reverse proxy вынесен на отдельный хост;
  • не публиковать внутренние сервисы наружу без необходимости;
  • содержать healthchecks.

Практически это должно быть управляемо через env вроде CRANK_PUBLISH_HOST:

  • 127.0.0.1 для local reverse proxy на том же Linux host;
  • конкретный внутренний IP или 0.0.0.0 для отдельного центрального reverse proxy в LAN.

10. Healthchecks

Нужны как минимум:

  • GET /health для admin-api
  • GET /health для mcp-server

CD не должен считать deployment успешным, пока эти endpoints не начали возвращать 200 OK.

11. CI и CD

11.1. CI

CI должен выполнять:

  • cargo fmt --all --check
  • cargo check --workspace
  • cargo clippy --workspace --all-targets --all-features -- -D warnings
  • cargo test --workspace --all-targets

11.2. CD

CD для MVP должен:

  • запускаться только после успешного CI на main или вручную;
  • собирать versioned container images;
  • пушить их в container registry с cache;
  • доставлять deployment files на целевой Linux host;
  • выполнять controlled restart через pull, без сборки на сервере;
  • проверять health endpoints после запуска.

Минимальный flow:

  1. push в main
  2. успешный CI
  3. build and push images в registry
  4. upload env и deployment files
  5. docker login на registry на целевом хосте
  6. docker compose config -q
  7. docker compose pull
  8. docker compose up -d
  9. healthcheck verification для ui, admin-api, mcp-server

Для текущего проекта базовая рекомендуемая схема:

  • GHCR как registry;
  • versioned tags по git sha;
  • docker/buildx cache в GitHub Actions;
  • на сервере только pull + restart, без docker compose up --build.

Для private registry на сервере нужны отдельные deployment secrets:

  • DEPLOY_REGISTRY_USER
  • DEPLOY_REGISTRY_TOKEN

Они используются только для docker login на целевом Linux host перед docker compose pull.

Для точечных runtime override без переписывания всего DEPLOY_ENV_FILE можно использовать отдельные deployment secrets. Сейчас поддержан:

  • DEPLOY_DEMO_SEED

Если он задан, workflow удаляет CRANK_DEMO_SEED из сгенерированного .env и записывает туда значение из DEPLOY_DEMO_SEED. Это позволяет временно включать и выключать demo seed отдельным secret, не переписывая основной production .env.

12. Что нельзя забыть

  • TLS и renewal сертификатов;
  • backup для postgres и artifact storage;
  • секреты вне репозитория;
  • app-level auth для admin-api и bootstrap admin credentials в env;
  • rollback на предыдущий image tag или предыдущую compose revision.
Reference in New Issue View Git Blame Copy Permalink