# Deployment

Документ описывает поддерживаемый путь деплоя Crank Community.

Crank Community запускается как три application containers за reverse proxy:

- `ui`
- `admin-api`
- `mcp-server`

Приложение использует внешний PostgreSQL. Compose manifest не поднимает
PostgreSQL самостоятельно.

## Runtime topology

```text
reverse proxy
  /            -> ui:3000
  /api/admin/  -> admin-api:3001
  /mcp/        -> mcp-server:3002

admin-api  -> PostgreSQL
mcp-server -> PostgreSQL
admin-api  -> optional Valkey/Redis
mcp-server -> optional Valkey/Redis
```

## Deployment files

- `deploy/community/docker-compose.yml`
- `deploy/community/.env.example`
- `.gitea/workflows/ci.yml`
- `.gitea/workflows/deploy.yml`
- `.gitea/workflows/release.yml`

## Порты

Default service ports:

- `ui`: `3000`
- `admin-api`: `3001`
- `mcp-server`: `3002`
- optional `valkey`: `6379`, только loopback

`CRANK_PUBLISH_BIND` управляет публикацией application ports:

- `127.0.0.1`, если reverse proxy работает на том же host;
- `0.0.0.0`, если reverse proxy работает на другом host.

## Reverse proxy

Пример `nginx`:

```nginx
server {
    listen 80;
    server_name crank.example.com;

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

server {
    listen 443 ssl http2;
    server_name crank.example.com;

    ssl_certificate /etc/letsencrypt/live/crank.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/crank.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://192.168.1.106:3000;
    }

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

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

Замените `192.168.1.106` на адрес deployment host.

## Compose

Проверка manifest:

```bash
docker compose \
  -f deploy/community/docker-compose.yml \
  --env-file deploy/community/.env.example \
  config -q
```

Запуск без внешнего cache:

```bash
docker compose \
  -f deploy/community/docker-compose.yml \
  --env-file deploy/community/.env.example \
  up -d
```

Запуск со встроенным Valkey:

```bash
docker compose \
  -f deploy/community/docker-compose.yml \
  --env-file deploy/community/.env.example \
  --profile cache \
  up -d
```

Для встроенного Valkey:

```text
CRANK_CACHE_BACKEND=valkey
CRANK_CACHE_URL=redis://valkey:6379/0
CRANK_CACHE_DEFAULT_TTL_MS=60000
```

## Health checks

```bash
curl http://127.0.0.1:3001/health
curl http://127.0.0.1:3002/health
```

Ожидаемые ответы:

```json
{"service":"admin-api","status":"ok"}
{"service":"mcp-server","status":"ok"}
```

UI root должен возвращать `200 OK`:

```bash
curl -I http://127.0.0.1:3000/
```

## Gitea CI/CD

Репозиторий использует Gitea Actions:

- `.gitea/workflows/ci.yml` запускает Rust, UI, E2E и deployment manifest checks.
- `.gitea/workflows/deploy.yml` собирает images и деплоит `main`.
- `.gitea/workflows/release.yml` собирает release artifacts для tags.

Deploy workflow читает из Gitea secrets только OpenBao bootstrap credentials:

- `BAO_ADDR`
- `BAO_ROLE_ID`
- `BAO_SECRET_ID`

Дальше workflow читает KV v2 secrets из OpenBao:

```text
ci/shared/registry
ci/shared/deploy-ssh
ci/projects/crank/deploy
ci/projects/crank/runtime
```

## Operational notes

- Бэкапы БД должны жить вне application host.
- Runtime secrets хранятся в OpenBao, не в Git.
- Для rollback используйте immutable image tags.
- `CRANK_PUBLISH_BIND=0.0.0.0` нужен только если другой host должен обращаться к published ports напрямую.