# Инструкция по развертыванию инфраструктуры (Bootstrap Guide) Плейбук называется машиной. В `roles/<машина>/` лежат продукты этой машины: один каталог, один Compose, один путь `/opt/<продукт>`. База и кэш остаются внутри Compose этого продукта. Роль `host` стоит отдельно: она готовит любую машину и ни одному продукту не принадлежит. Пайплайн подключается к машине, а применяет только роли, чьи файлы изменились (`--tags`). Роль `host` ставит пакеты, Docker и SSH. Она вызывается только из `playbooks/host.yml`, который подключает `site.yml`. Полный прогон и ручной запуск идут через `site.yml --limit <машина>`, поэтому подготовка машины выполняется один раз вместе с продуктами. Плейбук отдельной машины продукты ставит, машину не готовит. | Машина | Плейбук | Роли | Каталоги | |---|---|---|---| | `core-net` | `playbooks/core-net.yml` | `roles/core-net/traefik`; `roles/core-net/netbird`; `roles/core-net/remnawave`; `roles/core-net/vmagent`; `roles/core-net/authentik` *(опц., по умолчанию выкл.)* | `/opt/traefik`; клиент NetBird; `/opt/remnawave`; `/opt/vmagent`; `/opt/authentik` *(если включён)* | | `core-secrets` | `playbooks/core-secrets.yml` | `roles/core-secrets/infisical`, `roles/core-secrets/vaultwarden`, `roles/core-secrets/cadvisor` | `/opt/infisical`, `/opt/vaultwarden`, `/opt/cadvisor` | | `core-mon` | `playbooks/core-mon.yml` | `roles/core-mon/monitoring` | `/opt/monitoring` (VictoriaMetrics, vmalert, Grafana) | | `rus-central` | `playbooks/rus-central.yml` | `roles/rus-central/netbird`, `roles/rus-central/cadvisor` | `/opt/netbird`, `/opt/cadvisor` | | `ger-nod-02` | `playbooks/ger-nod-02.yml` | `roles/ger-nod-02/netbird`; `roles/ger-nod-02/remnanode`; `roles/ger-nod-02/vmagent` | клиент NetBird; `/opt/remnanode`; `/opt/vmagent` | | `opnsense` | `playbooks/opnsense.yml` | `roles/opnsense/netbird` | REST API (`192.168.1.1`) | Полная сверка одной машины: `ansible-playbook playbooks/site.yml --limit <машина>`. Gitea в автоматизацию не входит: без неё не запустить пайплайны. --- ## 1. Топология инфраструктуры ### 1.1. Физические узлы и гипервизоры (Proxmox VE) | Узел | IP | Роль | SSH / Доступ | |---|---|---|---| | **netcore** | `192.168.1.100:8006` | PVE Cluster Node / Core CTs | `root@192.168.1.100` (LAN only) | | **pve** | `192.168.1.2:8006` | PVE Main Node / Services | `root@192.168.1.2` (LAN only) | | **opnsense** | `192.168.1.1` | Маршрутизатор / Шлюз | Шлюз по умолчанию | Terraform в этом репозитории описывает только узел `netcore`. Узел `pve` и CT 109 поднимаются отдельно. ### 1.2. Базовые управляющие контейнеры (LXC / Debian 13) | CT ID | Хост PVE | IP | Имя хоста | Продукты | |---|---|---|---|---| | **CT 109** | `pve` | `192.168.1.217` | `gitea` | Gitea (`:3000`), Postgres (`:5432`), Gitea Actions Runner (`dind`) | | **CT 901** | `netcore` | `192.168.1.102` | `core-secrets` | Infisical (`:8080`), Postgres, Redis, Vaultwarden (`:8000`) | | **CT 902** | `netcore` | `192.168.1.104` | `core-net` | Traefik (`:80`, `:443`); Remnawave Panel (`127.0.0.1:3000`) + Subscription (`127.0.0.1:3010`); клиент NetBird (нужен `/dev/net/tun`); Authentik (`127.0.0.1:9000`) — опционально, по умолчанию выкл. | | **CT 903** | `netcore` | `192.168.1.108` | `core-mon` | VictoriaMetrics (`:8428`), vmalert (`127.0.0.1:8880`), Alertmanager (`:9093`), Grafana (`:3000`), Ntfy (`:80`) | ### 1.3. Внешние узлы | Имя | IP | Роль | Стек | |---|---|---|---| | **rus-central** | `45.154.185.208` | Внешний шлюз NetBird | `/opt/netbird`: NetBird и его собственный Traefik | | **ger-nod-02** | `150.241.64.209` | Remnawave Node (DE) + SelfSteal | `/opt/remnanode`: remnanode + nginx (`yali.gunis.top`) | Домен панели NetBird задаётся в `ansible/inventories/prod/host_vars/rus-central.yml`. Старая панель на Голове (`remna.gunihome.ru`) **не входит** в эту автоматизацию и не трогается. `ansible/roles/core-net/traefik/files/dynamic/` — известный бардак: плоский список старых и новых маршрутов. Имена вроде `tv.yml` — это поддомены, а не описание сервиса. Каталог разбирается после того, как вся старая инфраструктура переедет на роли машин. До этого файлы оттуда не переименовывать и не раскладывать. Подробности — в `README.md` внутри каталога. --- ## 2. Структура секретов в Infisical Проект: **`infra`** (Slug: `infra-xxx`, Environment: `prod`) API Endpoint (внутренний LAN): `http://192.168.1.102:8080/api` Внешний URL: `https://infisical.gunihome.ru` ### Пути секретов: - `/USER/ADMIN`: - `ADMIN_USER`: имя администратора хоумлаба (по умолчанию `karpenok`). - `ADMIN_PASSWORD`: единый пароль администратора (Traefik Dashboard, Grafana, Ntfy, NetBird). - `MAIL_ADMIN_USER`: почта администратора (для Grafana, NetBird и алертов). - `/ci-cd`: - `RUNNER_SSH_KEY`: приватный SSH-ключ раннера (ed25519) для деплоя на хосты. - `TF_STATE_TOKEN`: токен доступа к HTTP State Backend Gitea. - `CLOUDFLARE_API`: API-токен Cloudflare (Zone DNS Edit для `gunis.top`, DNS-01 сертификаты ноды). - `/VPS`: - `PASS_GER_NOD_02`: первичный root-пароль `ger-nod-02` (только bootstrap; после роли `host` вход по ключу). - `/services/infisical`: - `POSTGRES_PASSWORD`: пароль БД Infisical. - `ENCRYPTION_KEY`: 32-байтный hex-ключ шифрования хранилища. - `AUTH_SECRET`: base64 секрет сессий/JWT Infisical. - `/services/authentik` *(нужен только если включите Authentik)*: - `AUTHENTIK_SECRET_KEY`: случайный ключ шифрования сессий Authentik. - `AUTHENTIK_POSTGRES_PASSWORD`: пароль БД PostgreSQL Authentik. - `/services/netbird`: - `NETBIRD_LETSENCRYPT_EMAIL`: почта для сертификата. Если секрета нет, берётся `letsencrypt_email` из `group_vars/all.yml` или `MAIL_ADMIN_USER`. - `NETBIRD_AUTH_SECRET`: секрет auth. - `NETBIRD_DATASTORE_KEY`: 32-байтный ключ SQLite/datastore. - `NETBIRD_SESSION_KEY`: 32-байтный ключ веб-сессий. - `NETBIRD_API_TOKEN`: сервисный API-токен управления (создаётся и сохраняется пайплайном автоматически). - `NETBIRD_SETUP_KEY`: многоразовый ключ регистрации роутеров (`homelab-routers`). Панель и ноды им не пользуются. - `NETBIRD_REMNAWAVE_SETUP_KEY`: многоразовый ключ `remnawave-peers` для core-net и ger-nod-02. В группу роутеров не входит. - *(Параметры `NETBIRD_ADMIN_NAME`, `NETBIRD_ADMIN_PASSWORD`, `NETBIRD_ADMIN_EMAIL` наследуются из `/USER/ADMIN`)*. - `/services/opnsense`: - `OPNSENSE_API_KEY`: API-ключ администратора OPNsense. - `OPNSENSE_API_SECRET`: API-секрет администратора OPNsense. - `/services/remnawave`: - `REMNAWAVE_ADMIN_USER` / `REMNAWAVE_ADMIN_PASSWORD`: логин панели (Remnawave v3 требует пароль ≥24 с upper+lower+digit). Генерируются пайплайном при первом прогоне; **не** путать с `/USER/ADMIN`. - `REMNAWAVE_APP_SECRET`, `REMNAWAVE_POSTGRES_PASSWORD`, `REMNAWAVE_METRICS_PASS`, `REMNAWAVE_WEBHOOK_SECRET_HEADER`: генерируются пайплайном при первом прогоне, если пусто. - `REMNAWAVE_API_TOKEN`: сервисный API-токен панели (`infra-automation`, scopes `*`), создаётся и сохраняется пайплайном (при сбое — создать в UI и положить сюда вручную). - `REMNANODE_SECRET_KEY`: SECRET_KEY ноды Ger-nod-02 (`GET /api/keygen/`), сохраняется пайплайном. - `XRAY_CHECKER_SUBSCRIPTION_URL`: ссылка подписки пользователя `homelab` для Xray Checker на core-mon. В лог не пишется. - `/proxmox/netcore`: - `PROXMOX_ENDPOINT`: `https://192.168.1.100:8006/` - `PROXMOX_API_TOKEN`: токен `root@pam!terraform=UUID` Провайдер Proxmox сам дописывает `/api2/json`. В секрет его класть не нужно. Секреты `/proxmox/pve` этот репозиторий не читает: Terraform описывает только узел `netcore`. --- ## 3. Последовательность холодного старта (Cold Bootstrap) При полном отказе всех систем порядок восстановления следующий: ### Шаг 1. Гипервизоры и сеть 1. Поднять OPNsense (`192.168.1.1`). 2. Запустить Proxmox VE на `netcore` (`192.168.1.100`) и `pve` (`192.168.1.2`). 3. Убедиться в доступности SSH по ключам `root_home`. ### Шаг 2. Gitea & Gitea Actions (CT 109) 1. Запустить CT 109 на `pve`. 2. Запустить стек Gitea: `docker compose up -d` в каталоге Gitea. 3. Проверить доступность UI по адресу `http://192.168.1.217:3000`. 4. Убедиться, что раннер `gitea-runner` подключен и имеет статус `idle`. ### Шаг 3. Хранилище секретов Infisical (CT 901) > [!IMPORTANT] > Мастер-ключи начальной загрузки Infisical (`ENCRYPTION_KEY`, `AUTH_SECRET`, `POSTGRES_PASSWORD`) являются первоисточником шифрования и физически не могут храниться внутри самого Infisical. Они должны быть надежно сохранены в личном оффлайн-менеджере паролей администратора (KeePassXC / Bitwarden / 1Password). 1. Создать/запустить CT 901 (`core-secrets`, IP `192.168.1.102`). 2. Для первого старта вручную положить Compose Infisical в `/opt/infisical/compose.yaml` и подставить мастер-ключи из оффлайн-хранилища. Пайплайну эти ключи пока неоткуда прочитать. 3. Запустить контейнеры: `docker compose -f /opt/infisical/compose.yaml up -d`. 4. Проверить API: `curl http://192.168.1.102:8080/api/status`. 5. В Gitea Settings → Secrets добавить репозиторные секреты: - `INFISICAL_CLIENT_ID` (Machine Identity: `ci-cd-runner`) - `INFISICAL_CLIENT_SECRET` Дальше стек ведёт пайплайн **`ansible-core-secrets`**: Infisical в `/opt/infisical`, Vaultwarden в `/opt/vaultwarden`. ### Шаг 4. Traefik (CT 902) 1. Запустить пайплайн **`ansible-core-net`** в Gitea Actions. Первый прогон на новом CT должен быть полным: ручной запуск выполняет `site.yml --limit core-net` и ставит Docker ролью `host`. 2. Раннер подключается к `http://192.168.1.102:8080/api`, забирает SSH-ключ раннера и `ADMIN_*` из Infisical. Панель Traefik (`proxy.gunihome.ru`) закрывается BasicAuth из `/USER/ADMIN`. 3. Плейбук поднимает Traefik на CT 902. Роль Authentik в плейбуке есть, но **по умолчанию выключена** (`authentik_enabled=false` в defaults и в CI): compose не стартует, стек на cold bootstrap не нужен. 4. Проверить `https://proxy.gunihome.ru`, `https://gitea.gunihome.ru` и `https://infisical.gunihome.ru`. Правка только роли `traefik` ставит эту роль, без повторной подготовки машины. #### Authentik (опционально, не часть cold bootstrap) Стек оставляем в репозитории на будущее: SSO/forwardAuth для выбранных приложений, не для всего edge сразу. Чтобы включить: 1. Положить секреты в Infisical `/services/authentik` (`AUTHENTIK_SECRET_KEY`, `AUTHENTIK_POSTGRES_PASSWORD`). 2. Убрать принудительный `-e authentik_enabled=false` из `ansible/ci/deploy-machine.sh` (или передать `authentik_enabled=true` при ручном прогоне) и выставить `authentik_enabled: true`. 3. Прогнать `ansible-core-net` (или `--tags authentik`): стек слушает `127.0.0.1:9000`, снаружи — `https://auth.gunihome.ru`. Blueprints заводят группы `admins`/`family` и пользователей `karpenok`/`ksynia`; пароли blueprint не задаёт. Первый запуск создаёт `akadmin` (пароль в логе `authentik-server`). 4. На нужных роутерах Traefik повесить middleware `authentik` (forwardAuth из `roles/core-net/traefik/files/dynamic/authentik.yml`) — точечно, не на все сервисы. #### Remnawave Panel + Subscription (на core-net) Новая панель рядом с Traefik. Старый `remna.gunihome.ru` на Голове не затрагивается. 1. В Infisical положить: - `/ci-cd` → `CLOUDFLARE_API` - `/VPS` → `PASS_GER_NOD_02` (пароль нового VPS) 2. Запустить **`ansible-core-net`** (полный прогон или `--tags remnawave` после того, как Traefik уже с роутами `rw`/`sub`). 3. Роль поднимает `/opt/remnawave` (panel+db+redis) и `/opt/remnawave/subscription`, создаёт `REMNAWAVE_ADMIN_*`, каждый прогон **перевыпускает** API-токен `infra-automation` и кладёт его в Infisical (старый сразу недействителен). Config profile **`DE-Yali`**, сквад `Default-Squad` на inbound Steal-Yali, нода **`Ger-nod-02`**, host **`yali.gunis.top`**. Пользователи — файл `ansible/roles/core-net/remnawave/files/users.yml` (добавление/изменение/удаление = правка файла). Когда peer `ger-nod-02` уже есть в NetBird, адрес ноды в панели меняется на его NetBird IP. Пока peer нет, остаётся `150.241.64.209`. Ссылка подписки `homelab` пишется в `XRAY_CHECKER_SUBSCRIPTION_URL` и в лог не попадает. 4. Проверить `https://rw.gunihome.ru` и `https://sub.gunihome.ru`. > [!IMPORTANT] > **Логи:** шаги bootstrap и ошибки API видны в CI. Значения ключей туда не пишутся: stdout — только статус, секреты лежат в `/opt/remnawave/.bootstrap-secrets.json` (0600). `no_log` только у чтения этого файла, записи в Infisical и шаблона `.env`. В stderr поля `token` / `SECRET_KEY` / `privateKey` / `shortUuid` / пароли клиентов заменяются на `[REDACTED]`. ### Шаг 4b. Remnawave Node ger-nod-02 (SelfSteal) 1. После успешного `ansible-core-net` (чтобы в Infisical был `REMNANODE_SECRET_KEY`) запустить **`ansible-ger-nod-02`**. 2. Первый прогон: как у rus-central — `ansible_password` из `/VPS` → `PASS_GER_NOD_02`; роль `host` кладёт ключ и отключает пароль. Роль `remnanode` держит A-запись `yali.gunis.top` в Cloudflare, выпускает LE по **HTTP-01** (порт 80, без TXT `_acme-challenge` в зоне), поднимает remnanode + nginx SelfSteal. 3. В панели нода должна стать зелёной; браузер на `https://yali.gunis.top` — маскировочный сайт. 4. Клиент NetBird ходит на `https://central.gunihome.ru` ключом `remnawave-peers`. Пока peer панели не виден, `NODE_PORT` 2222 остаётся открыт для WAN egress панели. Когда peer `core-net` есть, 2222 разрешён только с его NetBird IP. Публичный `:9100` закрыт: метрики ноды уходят vmagent-ом в VictoriaMetrics на `192.168.1.108:8428` через маршрут `homelab-lan`. 5. На `core-net` (unprivileged LXC) `/dev/net/tun` сам не появляется. Токен Terraform получает 403: проброс устройства разрешён только `root@pam`. На netcore: `pct set 902 -dev0 /dev/net/tun,mode=0666 && pct reboot 902`, затем ещё раз `ansible-core-net`. До этого панель остаётся на публичном адресе ноды. ### Шаг 5. NetBird (rus-central) и связка с OPNsense 1. Запустить пайплайн **`ansible-rus-central`** в Gitea Actions. Ручной запуск сверяет машину целиком. Push в `roles/rus-central/netbird` ставит только NetBird. 2. Раннер считывает ключи из `/services/netbird`, деплоит стек в `/opt/netbird` на `45.154.185.208`, автоматически регистрирует первого суперпользователя (`POST /api/setup`), создаёт сервисный токен (`NETBIRD_API_TOKEN`), группу `homelab-routers`, маршрут к подсети `192.168.1.0/24` и многоразовый ключ установки (`NETBIRD_SETUP_KEY`). Отдельно создаётся группа `remnawave` и ключ `remnawave-peers` (`NETBIRD_REMNAWAVE_SETUP_KEY`): он не добавляет peer в `homelab-routers`. Оба ключа сохраняются в Infisical. 3. Запустить пайплайн **`ansible-opnsense`** в Gitea Actions. Раннер обращается по HTTPS REST API к `192.168.1.1`, проверяет/устанавливает плагин `os-netbird`, включает службу и регистрирует шлюз OPNsense на `https://central.gunihome.ru:443` по `NETBIRD_SETUP_KEY`.