image-gateway/docs/ci-cd.md

# CI/CD

Проект использует Gitea Actions workflows в `.gitea/workflows`.

## Прод Схема

В проде проект запускается через Docker Compose, а не через один общий Dockerfile.

Причины:

- `caddy` и `imgproxy` — разные runtime-сервисы;
- для Caddy нужен кастомный image с Souin, Otter и NutsDB modules;
- `imgproxy` берется как готовый upstream image `darthsim/imgproxy`;
- кешу нужны persistent volumes `caddy-data` и `caddy-cache`;
- Compose проще обновляет только Caddy image без пересборки на сервере;
- Image Gateway должен быть доступен только из сети внешнего reverse proxy.

В registry публикуется только кастомный Caddy image из `Dockerfile.caddy`. На сервере `docker-compose.yml` подставляет его через переменную `CADDY_IMAGE`.

Prod compose не публикует host-порты. Caddy подключается к external network `web` с alias `image-gateway`, поэтому внешний reverse proxy должен проксировать на `http://image-gateway:80` при `CADDY_PORT=80`.

## CI

Файл: `.gitea/workflows/ci.yml`.

Запускается на:

- push в `main`, `master`, `dev`;
- pull request в `main`, `master`, `dev`;
- ручной запуск через `workflow_dispatch`.

Что делает:

- проверяет `docker-compose.test.yml` через `docker compose config`;
- запускает e2e-тесты кеша через `./scripts/test-e2e.sh`;
- на основной ветке собирает и публикует Caddy image в Gitea Container Registry.

Публикуемые теги:

- branch tag, например `master` или `main`;
- commit SHA;
- `latest` для default branch.

## CD

Файл: `.gitea/workflows/deploy.yml`.

Запускается вручную через `workflow_dispatch`.

Что делает:

- вычисляет registry image текущего репозитория;
- подключается к серверу по SSH;
- копирует `docker-compose.yml` и `Caddyfile` в директорию деплоя;
- логинится в Gitea Container Registry;
- тянет `CADDY_IMAGE=<registry>/<repo>:latest`;
- создает Docker network внешнего reverse proxy, если ее еще нет;
- запускает `docker compose up -d --no-build`.

Сборка на прод-сервере не выполняется.

## Secrets

В Gitea repository secrets должны быть заданы:

| Secret | Назначение |
|---|---|
| `CR_USER` | пользователь Container Registry |
| `CR_TOKEN` | токен Container Registry |
| `SSH_PRIVATE_KEY` | приватный ключ для деплоя |

CD workflow использует те же registry и SSH secrets, что и другие проекты.

Настройки целевого сервера заданы в `env` файла `.gitea/workflows/deploy.yml`:

| Переменная | Значение по умолчанию | Назначение |
|---|---|---|
| `DEPLOY_HOST` | `188.225.47.78` | host/IP прод-сервера |
| `DEPLOY_USER` | `root` | SSH-пользователь |
| `DEPLOY_PATH` | `/opt/image-gateway` | директория проекта на сервере |
| `IMAGE_TAG` | `latest` | тег Caddy image для деплоя |
| `WEB_NETWORK` | `web` | Docker network внешнего reverse proxy |

На прод-сервере в `DEPLOY_PATH` должен лежать `.env` с runtime-настройками:

```env
DOMAIN=images.example.com
CADDY_PORT=80
WEB_NETWORK=web
IMGPROXY_KEY=
IMGPROXY_SALT=
IMGPROXY_ALLOWED_SOURCES=example.com,cdn.example.com
```

CD workflow не копирует `.env`, чтобы не перетирать секреты и runtime-настройки на сервере.

## Ручной Деплой На Сервере

Если нужно повторить деплой вручную на сервере:

```bash
cd /path/to/image-gateway
docker login registry.example.com
CADDY_IMAGE=registry.example.com/owner/image-gateway:latest docker compose -f docker-compose.yml pull caddy imgproxy
CADDY_IMAGE=registry.example.com/owner/image-gateway:latest docker compose -f docker-compose.yml up -d --no-build
```

## Reverse Proxy

Внешний reverse proxy должен быть подключен к той же Docker network, что и Image Gateway (`WEB_NETWORK`, по умолчанию `web`).

Внутренний upstream при `CADDY_PORT=80`:

```text
http://image-gateway:80
```

Прокидывайте исходный `Host`, чтобы Souin cache key не дробился по внутренним именам:

```text
Host: images.example.com
X-Forwarded-Proto: https
X-Forwarded-For: <client-ip>
```

Admin API `:2019` не должен публиковаться наружу.

## Skip CI

Для пропуска CI добавьте `[skip ci]` в сообщение коммита.