onGuard24/docs/CICD.md

CI/CD (Forgejo / Gitea) и деплой на pvestandt9

Цель: пуш тега v* → автоматический деплой на сервер; откат — повторный запуск workflow с другим тегом.

Что в репозитории

Файл	Назначение
.gitea/workflows/ci.yml	На push в main и PR: pytest.
.gitea/workflows/deploy.yml	На push тега v*: SSH на сервер → git checkout → docker compose build/up.
Dockerfile	Образ Python 3.12, pip install ., entrypoint: alembic upgrade + uvicorn.
docker-compose.yml	Сервис onguard24, порт 8080, env_file: .env.
deploy/entrypoint.sh	Перед стартом: alembic upgrade head (отключить: SKIP_ALEMBIC=1 в .env).

Включить Actions в Forgejo

1. Админка инстанса или репозитория: включить Actions.
2. Зарегистрировать runner с меткой ubuntu-latest (или изменить runs-on в YAML на вашу метку, например self-hosted).
3. Если образы actions/checkout недоступны, в настройках Actions задайте зеркало GitHub или используйте встроенные экшены Forgejo (см. документацию вашей версии).

Образ act_runner (Docker Hub)

Используйте gitea/act_runner (например тег nightly), а не docker.gitea.com/...:latest — последний часто недоступен.

sudo docker pull gitea/act_runner:nightly
sudo docker run -d --restart always --name act_runner \
  -e GITEA_INSTANCE_URL="https://forgejo.pvenode.ru" \
  -e GITEA_RUNNER_REGISTRATION_TOKEN="ТОКЕН_ИЗ_UI" \
  -e GITEA_RUNNER_NAME="pvestandt9" \
  -e GITEA_RUNNER_LABELS="ubuntu-latest:docker://catthehacker/ubuntu:act-22.04" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v act_runner_data:/data \
  gitea/act_runner:nightly

Стабильные теги: hub.docker.com/r/gitea/act_runner/tags.

Секреты репозитория

Настройки репозитория → Actions → Secrets:

Секрет	Пример	Описание
DEPLOY_HOST	pvestandt9 или IP	Хост SSH.
DEPLOY_USER	root	Пользователь SSH.
DEPLOY_SSH_KEY	содержимое id_rsa	Приватный ключ (весь PEM, многострочный).
DEPLOY_PATH	/opt/onGuard24	Каталог клона git на сервере (там же docker-compose.yml).

Ключ лучше отдельный deploy key только на чтение репозитория или полный доступ, если runner делает только git fetch.

Однократная подготовка сервера (root@pvestandt9)

ssh root@pvestandt9
apt-get update && apt-get install -y git docker.io docker-compose-v2
# или Docker CE по инструкции вашей ОС

mkdir -p /opt/onGuard24
cd /opt
git clone https://forgejo.pvenode.ru/admin/onGuard24.git onGuard24
cd onGuard24

Создайте /opt/onGuard24/.env (как в .env.example): DATABASE_URL, HTTP_ADDR (в контейнере порт задаёт compose; для приложения можно 0.0.0.0:8080), секреты Grafana и т.д.

Настройте git remote и доступ (~/.ssh deploy key или git credential), чтобы git fetch без пароля работал от пользователя, под которым заходит CI (часто root).

Проверка вручную:

cd /opt/onGuard24
docker compose build && docker compose up -d
curl -s http://127.0.0.1:8080/health

При необходимости пробросьте порт наружу (nginx, firewall).

Релиз (деплой новой версии)

1. Закоммитить код, запушить тег: git tag v1.6.0 && git push origin v1.6.0.
2. Workflow Deploy запустится сам, на сервере обновится код и пересоберётся контейнер.

Откат версии (простой процесс)

1. В Forgejo: Actions → Deploy → Run workflow.
2. В поле ref указать старый тег, например v1.4.1.
3. Запустить. На сервере выполнится checkout и reset на этот ref, затем docker compose build && up -d.

Убедитесь, что старый тег есть в origin (git push --tags не удалялся).

Миграции БД

По умолчанию при каждом старте контейнера выполняется alembic upgrade head. Если нужно отключить (и гонять миграции вручную), в .env на сервере: SKIP_ALEMBIC=1.

Устранение неполадок

• Runner не берёт job — проверьте runs-on и метки runner.
• SSH fails — ssh -i key root@DEPLOY_HOST с машины runner; known_hosts при необходимости добавьте в экшен (расширение appleboy/ssh-action / ssh-keyscan).
• git checkout fails — выполните на сервере git fetch --tags вручную, проверьте remote URL и ключ.
• База недоступна из контейнера — в DATABASE_URL укажите хост, доступный из Docker (не 127.0.0.1 хоста, если БД на хосте — используйте IP хоста или host.docker.internal где поддерживается).

См. также VERSIONING.md и IRM.md.