Refresh project documentation

deploy/README.md

@@ -2,27 +2,29 @@
 
 Минимальный `systemd`-деплой для `ignis-core`.
 
-В каталоге:
+Файлы:
 
-- `ignis-core.service` — unit-файл;
-- `ignis-core.env.example` — пример env-конфига.
+- `ignis-core.service` — unit-файл
+- `ignis-core.env.example` — пример env-конфига
 
-## Предполагаемая раскладка
+## Ожидаемая раскладка
 
 - код: `/opt/ignis/ignis-core`
 - env: `/etc/ignis-core/ignis-core.env`
 - пользователь: `ignis`
-- SQLite: `/var/lib/ignis-core/ignis.db`
+- база: `/var/lib/ignis-core/ignis.db`
 
-Если у вас другие пути, поправьте unit и env-файл.
+Если пути другие, поправьте unit и env.
 
-## 1. Создать системного пользователя
+## Установка
+
+### 1. Пользователь
 
 ```bash
 sudo useradd --system --home /opt/ignis --shell /usr/sbin/nologin ignis
 ```
 
-## 2. Разложить проект и зависимости
+### 2. Код и зависимости
 
 ```bash
 sudo mkdir -p /opt/ignis
@@ -34,7 +36,7 @@ pip install -r requirements.txt
 sudo chown -R ignis:ignis /opt/ignis
 ```
 
-## 3. Подготовить env-файл
+### 3. Env-файл
 
 ```bash
 sudo mkdir -p /etc/ignis-core
@@ -43,14 +45,13 @@ sudo chmod 640 /etc/ignis-core/ignis-core.env
 sudo chown root:ignis /etc/ignis-core/ignis-core.env
 ```
 
-Минимум, который надо заполнить руками:
+Минимум, который надо заполнить:
 
 - `IGNIS_API_KEY`
+- `IGNIS_INSTANCE_NAME`
 - `SCAN_NETWORK`
 
-Для машин с VPN или несколькими интерфейсами `SCAN_NETWORK` лучше задавать явно.
-
-## 4. Установить unit
+### 4. Unit
 
 ```bash
 sudo cp deploy/ignis-core.service /etc/systemd/system/ignis-core.service
@@ -58,14 +59,17 @@ sudo systemctl daemon-reload
 sudo systemctl enable --now ignis-core.service
 ```
 
-## 5. Проверить запуск
+## Проверка
 
 ```bash
 sudo systemctl status ignis-core.service
 sudo journalctl -u ignis-core.service -n 100 --no-pager
-curl -H 'X-API-Key: <master-key>' http://127.0.0.1:8000/auth/me
+curl -sS http://127.0.0.1:8000/auth/me -H 'X-API-Key: <master-key>'
+curl -sS http://127.0.0.1:8000/system/info -H 'X-API-Key: <master-key>'
 ```
 
+Если сервис стоит за reverse proxy, имеет смысл задать `IGNIS_PUBLIC_BASE_URL`.
+
 ## Обновление
 
 ```bash
@@ -75,9 +79,31 @@ pip install -r requirements.txt
 sudo systemctl restart ignis-core.service
 ```
 
-## Замечания
+Если менялся env:
 
-- `StateDirectory=ignis-core` в unit создаёт `/var/lib/ignis-core`.
-- По умолчанию сервис слушает `0.0.0.0:8000`.
-- Reverse proxy проще ставить перед сервисом, а не внутрь него.
-- Перед обновлением backend-контракта полезно перегенерировать `openapi.json` и прогнать `unittest`.
+```bash
+sudo systemctl restart ignis-core.service
+```
+
+Если менялся unit:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl restart ignis-core.service
+```
+
+## Что делает unit
+
+Текущий [ignis-core.service](ignis-core.service):
+
+- запускает `python -m uvicorn main:app --host 0.0.0.0 --port 8000`
+- читает `/etc/ignis-core/ignis-core.env`
+- рестартует сервис при падении
+- пишет состояние в `/var/lib/ignis-core`
+- даёт записи в `/opt/ignis/ignis-core` и `/var/lib/ignis-core`
+
+## Практические замечания
+
+- для хостов с VPN, Docker или несколькими интерфейсами лучше всегда задавать `SCAN_NETWORK` явно;
+- перед релизом полезно перегенерировать `openapi.json` и прогнать `unittest`;
+- reverse proxy лучше ставить перед сервисом, а не встраивать в него.

deploy/ignis-core.env.example

@@ -1,14 +1,25 @@
+# Auth and instance
 IGNIS_API_KEY=change-me
 IGNIS_INSTANCE_NAME=Home
+APP_TIMEZONE=Asia/Novosibirsk
+
+# Optional external URL and build metadata
 IGNIS_PUBLIC_BASE_URL=
 IGNIS_BUILD_VERSION=1.0.0
 IGNIS_BUILD_DATE=
 IGNIS_GIT_SHA=
-APP_TIMEZONE=Asia/Novosibirsk
+
+# Discovery
 SCAN_NETWORK=192.168.0.0/24
 DISCOVERY_INTERVAL_SECONDS=600
 DISCOVERY_BACKGROUND_MISSING_THRESHOLD=2
+DISCOVERY_ENV_MIN_PREFIX_LEN=16
+DISCOVERY_AUTO_MIN_PREFIX_LEN=24
+
+# Logging and retention
 LOG_LEVEL=INFO
 EVENT_LOG_RETENTION_DAYS=30
+
+# SQLite
 IGNIS_DATABASE_URL=sqlite+aiosqlite:////var/lib/ignis-core/ignis.db
 IGNIS_SYNC_DATABASE_URL=sqlite:////var/lib/ignis-core/ignis.db