# Руководство разработчика

## Требования

- Docker
- Docker Compose

## Режимы запуска

### Development (`docker-compose.dev.yml`)

Bridge-сеть, проброс портов:
- `8888` — Caddy (изображения)
- `2019` — Caddy Admin API (Souin purge)

```bash
docker compose -f docker-compose.dev.yml up -d --build
docker compose -f docker-compose.dev.yml down
docker compose -f docker-compose.dev.yml logs -f caddy
docker compose -f docker-compose.dev.yml logs -f imgproxy
```

### Production (`docker-compose.yml`)

Bridge-сеть, порт `80` (или `443` с HTTPS). Порт 2019 **не пробрасывается** — доступен только внутри Docker сети.

```bash
docker compose up -d --build
```

## Конфигурация

Все настройки через `.env` файл (см. `.env.example`).

### imgproxy

| Переменная | Описание | По умолчанию |
|---|---|---|
| `IMGPROXY_KEY` | Hex-ключ для подписи URL (пусто = unsigned) | — |
| `IMGPROXY_SALT` | Hex-соль для подписи URL | — |
| `IMGPROXY_WORKERS` | Количество воркеров обработки | `2` |
| `IMGPROXY_MAX_SRC_RESOLUTION` | Макс. разрешение исходника (MP) | `20` |
| `IMGPROXY_ALLOWED_SOURCES` | Whitelist доменов (через запятую) | — |
| `IMGPROXY_DOWNLOAD_TIMEOUT` | Таймаут загрузки исходника (сек) | `30` |

### Caddy

| Переменная | Описание | По умолчанию |
|---|---|---|
| `CADDY_PORT` | Порт Caddy | `8888` (dev) / `80` (prod) |
| `DOMAIN` | Домен для HTTPS (пусто = localhost, prod only) | — |

### Сеть (опционально)

| Переменная | Описание |
|---|---|
| `HTTP_PROXY` | HTTP-прокси для imgproxy |
| `HTTPS_PROXY` | HTTPS-прокси для imgproxy |
| `NO_PROXY` | Исключения прокси |

### Генерация ключей подписи

```bash
openssl rand -hex 32  # KEY
openssl rand -hex 32  # SALT
```

## HTTPS (production)

Укажите домен в `.env`:

```env
DOMAIN=images.example.com
```

Caddy автоматически получит Let's Encrypt сертификат.

## Интеграция с внешними сервисами

Next.js или другой сервис внутри Docker сети ходит к Caddy Admin API для purge:

```
http://caddy:2019/souin-api/souin/        — GET список ключей
http://caddy:2019/souin-api/souin/flush    — PURGE полный сброс
http://caddy:2019/souin-api/souin/{regex}  — PURGE по regex
```

Для добавления Next.js в сеть — подключить контейнер к сети `gateway`:

```yaml
services:
  app:
    # ...
    networks:
      - gateway

networks:
  gateway:
    external: true
    name: image-gateway_gateway
```

## Корпоративная сеть

```env
HTTP_PROXY=http://proxy.company.com:8080
HTTPS_PROXY=http://proxy.company.com:8080
NO_PROXY=localhost,127.0.0.1,.company.com
```

`GODEBUG=http2client=0` уже задан в compose — отключает HTTP/2 в Go, решает проблемы с Cloudflare через прокси.

## Мониторинг

### Cache-Status заголовок

```
Cache-Status: Souin; hit; ttl=31535999; detail=DEFAULT          # из кеша
Cache-Status: Souin; fwd=uri-miss; stored; key=GET-...          # закешировано
Cache-Status: Souin; fwd=uri-miss; detail=UNCACHEABLE-...       # не закешировано
```

### Логи

```bash
docker compose -f docker-compose.dev.yml logs -f caddy     # Caddy + Souin
docker compose -f docker-compose.dev.yml logs -f imgproxy  # imgproxy
```