diff --git a/README.md b/README.md index 1714fb9..0f36f1a 100644 --- a/README.md +++ b/README.md @@ -54,10 +54,16 @@ make up # docker compose -f ../docs/dev/docker-compose.yml up -d ``` `make up` поднимает `postgres` (5432), `nats` (4222, мониторинг 8222), `minio` (9000, консоль 9001) и одноразовый -`minio-init`, который создаёт бакет `arm-ka` и завершается с кодом 0. Готовность — «healthy» у трёх долгоживущих -сервисов: `docker compose -f ../docs/dev/docker-compose.yml ps`. Для скриптов, которым нужно дождаться готовности: -`docker compose -f ../docs/dev/docker-compose.yml up -d --wait postgres nats minio` (голый `--wait` возвращает код 1 -из-за завершающегося `minio-init`). Подробности, смена портов, сброс — [`../docs/dev/README.md`](../docs/dev/README.md). +`minio-init`, который создаёт бакет `arm-ka` и завершается с кодом 0. Команда возвращается сразу, а PostgreSQL становится +готовым примерно через 6 секунд: **дождитесь `healthy`** у трёх долгоживущих сервисов, прежде чем выполнять `make migrate`: + +```bash +docker compose -f ../docs/dev/docker-compose.yml up -d --wait postgres nats minio # возвращается, когда все healthy +docker compose -f ../docs/dev/docker-compose.yml ps # проверка статуса +``` + +(голый `--wait` без списка сервисов возвращает код 1 из-за завершающегося `minio-init`; поэтому `make up` для бакета +и `--wait` со списком — вместе). Подробности, смена портов, сброс — [`../docs/dev/README.md`](../docs/dev/README.md). ### 3. Настройки приложения @@ -149,11 +155,22 @@ Dev-пользователи (`api/seed/dev/users.yaml`, создаются `mak ### Что вы увидите в логе при запуске -- Предупреждение «Включён dev-эмитент токенов … только для разработки» — штатно (см. «Безопасность dev-режима»). -- Трейсбэк `ClientConnectorSSLError ... localhost:9000` при проверке бакета MinIO. Клиент S3 из шаблона ходит по - `https`, а MinIO из compose слушает `http`. Приложение стартует и работает, S3 в Срезе 0 не используется - (`app.state.storage` остаётся пустым). Недоступность S3 или NATS при старте приложение не роняет: ошибка логируется, - а состояние NATS видно в `/healthcheck`. +Старт занимает около секунды; в логе два трейсбэка — это ожидаемо в dev, приложение при этом работает: + +- Трейсбэк SMB: `Ошибка при регистрации сессии SMB ... Failed to connect to 'localhost:445': Connection refused`. + Настройки `OPENBAO__SMB__*` — заглушки, SMB в Срезе 0 не используется; игнорируйте. Пока на `localhost:445` ничего + не слушает, отказ приходит сразу (старт не задерживается); если порт отвечает, но молчит, ожидание ограничено + тайм-аутом `smbclient` (60 с). +- Трейсбэк S3: `ClientConnectorSSLError ... localhost:9000`. Клиент S3 из шаблона ходит по `https`, а MinIO из compose + слушает `http`. S3 в Срезе 0 не используется (`app.state.storage` остаётся пустым). Это до исправления в задаче 22 + (отдельная настройка схемы подключения к MinIO). + +Недоступность SMB, S3 или NATS при старте приложение не роняет: ошибка логируется, состояние NATS видно в +`/healthcheck`. + +Предупреждение «Включён dev-эмитент токенов … только для разработки» появляется не при старте, а при первом +запросе к защищённому эндпоинту (`/api/v1/me`): проверяющий токены создаётся лениво (штатно, см. «Безопасность +dev-режима»). ### Остановка и сброс @@ -180,10 +197,16 @@ docker compose -f ../docs/dev/docker-compose.yml down -v # полный сб | `VERSION` | `1.0.0` | версия в `/healthcheck` и OpenAPI | | `OPENBAO__DATABASE__DATABASE_URL` | — (обязательно) | PostgreSQL, драйвер asyncpg: `postgresql+asyncpg://armka:armka@localhost:5432/armka` | | `OPENBAO__MINIO__MINIO_URL` | — (обязательно) | адрес MinIO без схемы (`host:port`, так ждёт `miniopy-async`) | -| `OPENBAO__MINIO__MINIO_ADMIN_LOGIN`, `..._PASSWORD`, `..._BUCKET` | — (обязательно) | учётные данные и бакет MinIO | +| `OPENBAO__MINIO__MINIO_ADMIN_LOGIN` | — (обязательно) | логин MinIO | +| `OPENBAO__MINIO__MINIO_ADMIN_PASSWORD` | — (обязательно) | пароль MinIO | +| `OPENBAO__MINIO__MINIO_BUCKET` | — (обязательно) | бакет MinIO (`arm-ka`) | | `OPENBAO__NATS__NATS_URL` | — (обязательно) | адрес NATS (`nats://localhost:4222`) | -| `OPENBAO__NATS__NATS_SEED`, `OPENBAO__NATS__NATS_JWT` | пусто | nkeys; пусто — подключение без учётных данных (compose, тесты). Задаются оба или ни одного | -| `OPENBAO__SMB__SMB_HOST`, `SMB_PATH`, `SMB_LOGIN`, `SMB_PASSWORD` | — (обязательно) | заглушки SMB (в Срезе 0 не используется, блок обязателен) | +| `OPENBAO__NATS__NATS_SEED` | пусто | nkey seed; пусто — подключение без учётных данных (compose, тесты). Задаётся вместе с `NATS_JWT` или не задаётся вовсе | +| `OPENBAO__NATS__NATS_JWT` | пусто | JWT NATS; см. `NATS_SEED` | +| `OPENBAO__SMB__SMB_HOST` | — (обязательно) | заглушка SMB (в Срезе 0 не используется, блок обязателен) | +| `OPENBAO__SMB__SMB_PATH` | — (обязательно) | заглушка SMB | +| `OPENBAO__SMB__SMB_LOGIN` | — (обязательно) | заглушка SMB | +| `OPENBAO__SMB__SMB_PASSWORD` | — (обязательно) | заглушка SMB | | `NATS_ENABLED` | `false` | подключение к NATS и обмен через `recognition_job`; без него `/healthcheck` показывает `nats=off` | | `OUTBOX_POLL_SECONDS` | `5` | период опроса outbox | | `ACK_TIMEOUT_SECONDS` | `30` | ожидание ack сервиса распознавания до повторной публикации | @@ -231,7 +254,8 @@ docker compose -f ../docs/dev/docker-compose.yml down -v # полный сб и удаляется в конце. Параметры подключения берутся из `api/.env.test` (`pytest.ini` задаёт `ENV_FILE=.env.test`). Сейчас этот файл указывает на временную тестовую инфраструктуру (PostgreSQL `55432`, NATS `54222`, MinIO `59000`), а не на стандартные порты compose: чтобы гонять интеграционные тесты против `make up`, поправьте порты в - `api/.env.test` на `5432`, `4222`, `9000` (не коммитьте это изменение без согласования). + `api/.env.test` на `5432`, `4222`, `9000` (не коммитьте это изменение без согласования). То же относится к + `make migration-cycle` и `make check-full`: они тоже читают `.env.test` через `pytest.ini`. - **Реальные данные** — репозиторий `../fixtures/` (путь можно задать переменной `ARM_KA_FIXTURES`). Тесты с маркером `fixtures` без каталога пропускаются с понятной причиной.