vbev.dev/README.md

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 и сертификатов.
db	postgres:16-alpine	Общий PostgreSQL для сервисов стека; сейчас используется Synapse.
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.
msg	matrixdotorg/synapse:v1.160.0	Matrix homeserver Synapse для чатов, E2EE, файлов и клиентского API.
msg-web	vectorim/element-web:v1.12.27	Element Web, браузерный клиент Matrix.
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 и задайте значения для своей среды:

cp .env.example .env

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

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

Matrix-переменные задаются не в .env, а в Gitea variables: deploy workflow использует их для генерации config secrets. MATRIX_SERVER_NAME выбирайте заранее: это часть Matrix ID пользователей, например @alice:matrix.example.com, и менять это имя после запуска нельзя без миграции на новый homeserver. MATRIX_PUBLIC_BASEURL должен быть публичным URL Synapse через reverse proxy, обычно https://matrix.example.com. ELEMENT_WEB_URL должен указывать на браузерный Element Web, например https://chat.example.com.

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

secrets/postgres_admin_password.txt
secrets/synapse_postgres_password.txt
secrets/synapse_homeserver_config.yaml
secrets/element_config.json
secrets/vaultwarden_admin_token.txt
secrets/beszel_agent_key.txt
secrets/beszel_agent_token.txt
secrets/gitea_runner_registration_token.txt

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

chmod 700 secrets
chmod 600 secrets/*.txt
chmod 644 secrets/synapse_homeserver_config.yaml secrets/element_config.json

Не коммитьте .env, secrets/ и data/. .env содержит несекретные значения окружения; secrets/ содержит секреты и generated runtime-конфиги. Credential-файлы в secrets/*.txt закрываются как 600; config-файлы для Docker mounts остаются 644, потому что Docker Compose file secrets монтируются как bind mounts и должны читаться non-root контейнерами. На хосте доступ к ним ограничен правами 700 на директорию secrets/. В data/ находятся базы данных, пользовательские файлы, сгенерированные ключи, сертификаты и другое runtime-состояние.

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

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

docker compose config

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

docker compose up -d

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

docker compose ps
docker compose logs -f <service>

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

docker compose pull
docker compose up -d

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

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

docker compose down

Данные

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

data/nginx-proxy-manager/
data/vaultwarden/
data/beszel/
data/nextcloud/
data/postgres/
data/synapse/
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. Подготавливает generated runtime-конфиги из шаблонов и Gitea variables/secrets.
7. Создает на сервере .env, secrets/*.txt и generated config secrets.
8. Запускает db и выполняет идемпотентную инициализацию PostgreSQL через ops/postgres/init-services.sh.
9. Скачивает images и запускает docker compose -f docker-compose-<ref>.yml up -d --remove-orphans.
10. Отправляет Telegram-уведомление об успехе или ошибке и прикладывает deploy log.

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

DEPLOY_DIRECTORY
DEPLOY_BACKUP_ENABLED
DEPLOY_DRY_RUN_ENABLED
BESZEL_HUB_URL
GIT_URL
NEXTCLOUD_DOMAIN
RUSTDESK_DOMAIN
MATRIX_SERVER_NAME
MATRIX_PUBLIC_BASEURL
ELEMENT_WEB_URL

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

SSH_HOST
SSH_USERNAME
SSH_PASSWORD
BESZEL_AGENT_KEY
BESZEL_AGENT_TOKEN
POSTGRES_ADMIN_PASSWORD
SYNAPSE_POSTGRES_PASSWORD
SYNAPSE_REGISTRATION_SHARED_SECRET
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.

Matrix

Matrix-компоненты в текущем стеке:

db         PostgreSQL, общая БД стека
msg        Synapse homeserver
msg-web    Element Web

PostgreSQL users/databases подготавливаются deploy workflow через ops/postgres/init-services.sh. Скрипт передается в init-контейнер через SSH stdin, поэтому не остается на сервере отдельным файлом. Скрипт идемпотентный: его можно запускать повторно, он создает недостающие сущности и не пересоздает уже существующие.

Для Nginx Proxy Manager создайте два proxy host:

matrix.example.com -> http://msg:8008
chat.example.com   -> http://msg-web:80

Для Synapse proxy host нужен WebSocket support и стандартные forwarded headers. На этом этапе federation и TURN не добавлены: scope ограничен БД, Synapse и Element Web.

Synapse читает runtime-конфиг из Docker secret synapse_homeserver_config, а Element Web - из Docker secret element_config. Deploy workflow создает source-файлы этих secrets в secrets/synapse_homeserver_config.yaml и secrets/element_config.json из шаблонов. В Git хранятся только config/synapse/homeserver.yaml.template и config/element/config.json.template. Для локального запуска создайте оба runtime-файла в secrets/ из шаблонов и подставьте свои значения.

Регистрация в Synapse закрыта; пользователей создавайте вручную после запуска:

docker compose exec msg register_new_matrix_user -c /run/secrets/synapse_homeserver_config http://localhost:8008

Gitea secret SYNAPSE_REGISTRATION_SHARED_SECRET попадает в generated secrets/synapse_homeserver_config.yaml и используется для админского создания пользователей через эту команду. Не меняйте его после первого запуска без причины.

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

• Запускайте 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-сервисов.