Files
buryan-infra/deploy/README.md

153 lines
8.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# deploy/ — compose-файлы по контейнерам
Правило: **Git — источник истины**. Файл из `deploy/ctNNN/docker-compose.yml`
копируется на контейнер в `/opt/ctNNN/docker-compose.yml` и оттуда запускается.
Ручной `docker run` больше не используется: иначе состояние контейнера и
репозиторий расходятся, и при следующем аудите находится «порт съехал»
(реальный случай: n8n 5678 в копии скрипта против живого 5680).
## Секреты
В compose-файлах **нет** значений секретов — только переменные `${VAR}`.
Значения лежат рядом в `.env` (права 600, в Git не попадает), образец —
`env.example`. Сами значения — в Vaultwarden, папка `infra`.
## Применение
```bash
# на контейнере
cd /opt/ctNNN
docker compose up -d
```
Перед изменением состава контейнеров — снапшот: `pct snapshot NNN <метка>`.
## Что уже переведено
| CT | Файл | Состав | Примечание |
|---|---|---|---|
| 140 | `ct140/docker-compose.yml` | gitea, gitea-runner, promtail, beszel-agent | 28.10.2026: три контейнера были «руками», теперь все четыре под compose. Ловушка AppArmor — в `ops/gitea/RUNNER-APPARMOR-2026-10-28.md` |
## Известные особенности CT140
* `security_opt: apparmor:unconfined` обязателен для **каждого** контейнера:
внутри CT140 Docker не может загрузить профиль `docker-default`.
* У `gitea-runner` дополнительно `CONFIG_FILE=/data/config.yaml` — без этой
переменной `run.sh` не передаёт `--config`, и опция `container.options`
(нужная, чтобы job-контейнеры стартовали) молча игнорируется.
## Ловушки, пойманные при переносе (28.10.2026)
* **promtail без `-config.file`** читает встроенный конфиг образа — в нём нет
`clients`, и контейнер падает: `at least one client config must be provided`.
Поэтому в compose у promtail всегда есть
`command: ["-config.file=/etc/promtail/config.yml"]`.
* **Позиции promtail нельзя держать в `/tmp`**: при пересоздании контейнера они
теряются, promtail начинает перечитывать старые логи, а Loki отбрасывает их
(`timestamp too old`) — поток ошибок в логе. Позиции вынесены на хост:
`/opt/promtail-positions:/var/lib/promtail`.
* **Генератор читает живое состояние.** Если в момент генерации в контейнере
висит временный контейнер (например, тестовый), он попадёт в файл. Поэтому
`docker-to-compose.py` без `--force` не перезаписывает существующий
`deploy/ctNNN/docker-compose.yml`.
## Снапшоты недоступны на 12 CT (важно для правила «сначала снапшот»)
Проверено 28.10.2026: `pct snapshot` возвращает `snapshot feature is not available`,
если у контейнера есть bind-монтирование (`mpX`). Такие CT:
`103, 105, 109, 111, 117, 118, 120, 123, 125, 126, 155, 160`
Например, CT103: `mp0: /mnt/media,mp=/media`.
Что делать вместо снапшота:
```bash
# 1. сохранить конфиг (секунды, обратимо руками)
cp /etc/pve/lxc/103.conf /root/lxc-conf-103-$(date +%Y%m%d-%H%M).bak
# 2. если меняется что-то серьёзное — полный дамп (дольше)
vzdump 103 --storage /mnt/archive/backups/dump --mode suspend --compress zstd
```
Для правок, которые касаются только контейнеров внутри CT (Docker в rootfs),
данные на `/mnt/media` не затрагиваются — но это надо осознанно принять,
а не считать, что снапшот есть.
## Обязательное требование: плагин compose
Перед переносом проверять, что в CT есть плагин:
```bash
pct exec NNN -- docker compose version
```
28.10.2026 на CT124 и CT126 плагина не было: `docker compose up` молча упал,
а контейнеры к этому моменту уже были удалены — frigate (запись камер) и
jackett стояли около 3 минут. Восстановлены через `docker run` из
`deploy/ctNNN/docker-compose.yml`, затем плагин установлен:
```bash
mkdir -p /usr/local/lib/docker/cli-plugins
python3 -c "import urllib.request;urllib.request.urlretrieve('https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64','/usr/local/lib/docker/cli-plugins/docker-compose')"
chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
```
Правило: сначала убедиться, что `docker compose version` работает,
и только потом удалять контейнеры.
## CT113: несовместимость compose с dockerd — решено (28.10.2026)
В CT113 dockerd 20.10 (API 1.41), а пакетный `docker-compose-plugin` 5.1 требует
более новый API: `client version 1.53 is too new`. Обновлять dockerd на CT с
Loki/Grafana рискованно, поэтому поставлен совместимый compose в /usr/local
(он приоритетнее пакетного):
```bash
mkdir -p /usr/local/lib/docker/cli-plugins
python3 -c "import urllib.request;urllib.request.urlretrieve('https://github.com/docker/compose/releases/download/v2.24.7/docker-compose-linux-x86_64','/usr/local/lib/docker/cli-plugins/docker-compose')"
chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
docker compose version # v2.24.7
```
После этого все четыре сервиса CT113 (loki, promtail, oauth2-proxy-backup,
beszel-agent) запускаются из compose. `loki /ready` → 200.
Ещё одна ловушка того же дня: если часть контейнеров создана `docker run`,
`compose up` упирается в `Conflict. The container name is already in use`.
Правильно — удалить все контейнеры сервисов по одному, затем `compose up -d`.
## Правило: сверять до удаления
28.10.2026 генератор терял аргументы запуска (поле `Cmd`, а не `Command`):
loki, alertmanager, четыре exportarr и webhook поднялись без нужных флагов.
Итог — observability лежала около 20 минут.
Перед удалением контейнеров запускать сверку:
```bash
python3 ops/scripts/check-compose-parity.py 134
# CT134: сервисов 8, расхождений 0
```
Скрипт сравнивает image, entrypoint, command, ключи env, монтирования и порты
между `deploy/ctNNN/docker-compose.yml` и живым контейнером. Ненулевой код
возврата = расхождения есть, удалять контейнеры нельзя.
## Итог перевода: 26 из 26 CT (28.10.2026)
Все контейнеры, созданные `docker run`, описаны в `deploy/ctNNN/docker-compose.yml`.
Исключение — `loki` в CT113: там compose несовместим с dockerd, контейнер
запускается `docker run` (см. раздел про CT113).
### Ещё одна пойманная ловушка
`docker rm -f a b c` **прерывается на первом отсутствующем имени** и остальные
не удаляет. Из-за этого в CT155 при переносе остался старый `promtail`, новый
`compose up` упал на конфликте имени, а `matrix-synapse` и `matrix-coturn` при
этом не создались — Matrix лежал около 5 минут, пока не удалил контейнер
вручную и не поднял всё чисто.
Правило: удалять контейнеры по одному (`docker rm -f NAME` в цикле с `|| true`)
и после `up` проверять не только «контейнер запущен», но и что он в списке.