211 lines
10 KiB
Markdown
211 lines
10 KiB
Markdown
# 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` и задайте значения для своей среды:
|
||
|
||
```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
|
||
```
|
||
|
||
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`.
|
||
|
||
Перед запуском сервисов, которым нужны секреты, создайте файлы:
|
||
|
||
```text
|
||
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
|
||
```
|
||
|
||
Рекомендуемые права:
|
||
|
||
```sh
|
||
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-файл:
|
||
|
||
```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/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:
|
||
|
||
```text
|
||
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:
|
||
|
||
```text
|
||
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-компоненты в текущем стеке:
|
||
|
||
```text
|
||
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:
|
||
|
||
```text
|
||
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 закрыта; пользователей создавайте вручную после запуска:
|
||
|
||
```sh
|
||
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-сервисов.
|