# vbevdev

Self-hosted инфраструктурный стек, управляемый через Docker Compose.

Репозиторий содержит Compose-описание сервисов, workflow для деплоя и пример переменных окружения. Runtime-данные и секреты намеренно не хранятся в Git.

## Сервисы

| Сервис | Image | Назначение |
| --- | --- | --- |
| `prx` | `jc21/nginx-proxy-manager:2.15.1` | Nginx Proxy Manager для reverse proxy, HTTP/HTTPS и сертификатов. |
| `pwd` | `vaultwarden/server:1.37.1` | Vaultwarden, менеджер паролей. |
| `mon` | `henrygd/beszel` | Beszel monitoring hub. |
| `mon-agent` | `henrygd/beszel-agent` | Beszel monitoring agent с доступом к Docker socket. |
| `cld` | `nextcloud:30.0.6` | Nextcloud. |
| `git` | `docker.gitea.com/gitea:1.26.2` | Gitea server. |
| `git-runner` | `gitea/act_runner:latest` | Gitea Actions runner. |
| `sup-hbbs` | `rustdesk/rustdesk-server:latest` | RustDesk ID/rendezvous server. |
| `sup-hbbr` | `rustdesk/rustdesk-server:latest` | RustDesk relay server. |

Docker network по умолчанию называется `vbevdev`.

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

Создайте локальный `.env` из `.env.example` и задайте значения для своей среды:

```sh
cp .env.example .env
```

Обязательные переменные:

```sh
BESZEL_HUB_URL=http://mon.localhost
NEXTCLOUD_DOMAIN=cld.localhost
GITEA_URL=http://git:3000
RUSTDESK_DOMAIN=sup.local
```

Перед запуском сервисов, которым нужны секреты, создайте файлы:

```text
secrets/vaultwarden_admin_token.txt
secrets/beszel_agent_key.txt
secrets/beszel_agent_token.txt
secrets/gitea_runner_registration_token.txt
```

Рекомендуемые права:

```sh
chmod 700 secrets
chmod 600 secrets/*.txt
```

Не коммитьте `.env`, `secrets/` и `data/`. В них находятся локальная конфигурация, credentials, базы данных, пользовательские файлы, сгенерированные ключи, сертификаты и другое runtime-состояние.

## Локальные операции

Проверить Compose-файл:

```sh
docker compose config
```

Запустить или обновить стек:

```sh
docker compose up -d
```

Посмотреть состояние и логи:

```sh
docker compose ps
docker compose logs -f <service>
```

Скачать новые images и пересоздать контейнеры:

```sh
docker compose pull
docker compose up -d
```

Для stateful-сервисов с данными в `data/` фиксируйте конкретные версии images вместо `latest`. Обновление версии делайте отдельным изменением после просмотра release notes и backup соответствующей директории в `data/`.

Остановить стек без удаления runtime-данных:

```sh
docker compose down
```

## Данные

Persistent-данные контейнеров монтируются в `./data`:

```text
data/nginx-proxy-manager/
data/vaultwarden/
data/beszel/
data/nextcloud/
data/gitea/
data/rustdesk/
```

Эта директория является runtime-состоянием, а не исходным кодом. Делайте backup перед destructive Docker-командами, изменением volume, миграциями и обновлениями stateful-сервисов.

## Деплой

Деплой описан в `.gitea/workflows/deploy.yaml` и запускается вручную через `workflow_dispatch`.

Workflow деплоя:

1. Забирает репозиторий.
2. Нормализует имя ref/branch для имени удаленного Compose-файла.
3. Настраивает SSH через `.gitea/actions/configure-ssh-client`.
4. Опционально создает архив `data/`, если `DEPLOY_BACKUP_ENABLED` равен `true`.
5. Копирует `docker-compose.yml` на сервер как `docker-compose-<ref>.yml`.
6. Создает на сервере `.env` и `secrets/*.txt` из Gitea variables и secrets.
7. Скачивает images и запускает `docker compose -f docker-compose-<ref>.yml up -d --remove-orphans`.
8. Отправляет Telegram-уведомление об успехе или ошибке и прикладывает deploy log.

Используемые Gitea variables:

```text
DEPLOY_DIRECTORY
DEPLOY_BACKUP_ENABLED
DEPLOY_DRY_RUN_ENABLED
BESZEL_HUB_URL
GIT_URL
NEXTCLOUD_DOMAIN
RUSTDESK_DOMAIN
```

Используемые Gitea secrets:

```text
SSH_HOST
SSH_USERNAME
SSH_PASSWORD
BESZEL_AGENT_KEY
BESZEL_AGENT_TOKEN
RUNNER_REGISTRATION_TOKEN
VAULTWARDEN_ADMIN_TOKEN
TELEGRAM_DEPLOY_BOT_TOKEN
TELEGRAM_DEPLOY_CHAT_ID
PROXY_URL
```

Workflow `.gitea/workflows/test_telegram_deploy_bot.yaml` можно запускать вручную для проверки Telegram-уведомлений через настроенный proxy.

## Сопровождение

- Запускайте `docker compose config` после изменений в `docker-compose.yml`.
- Держите `.env.example` синхронизированным с переменными, которые использует Compose.
- Держите Gitea variables/secrets синхронизированными с `.gitea/workflows/deploy.yaml`.
- Делайте backup `data/` перед обновлениями, сменой images, изменением volumes и миграциями.
- Перед изменением pinned image versions проверяйте release notes stateful-сервисов.