# Инструкция по установке

Программное обеспечение «Универсальная платформа-конструктор сбора, обработки и согласования данных»

Редакция документа: 1.1. Дата: 21.09.2026.

## 1. Назначение и схема развертывания

«Универсальная платформа-конструктор сбора, обработки и согласования данных» разворачивается и обслуживается через Docker Compose. Backend, PostgreSQL и Redis работают в контейнерах. В промышленной эксплуатации frontend также работает в контейнере. Только при разработке frontend и его библиотека docomo-ui собираются локально, а сервер разработки frontend запускается на машине разработчика.

Python, uv и PostgreSQL на хост для эксплуатации приложения устанавливать не требуется. Команды backend, включая миграции, выполняются внутри контейнера средствами docker compose run или exec. Процесс backend запускается командой, заданной в Dockerfile.

Все команды Docker в документе выполняются из корня репозитория. Нужны исходные каталоги backend, frontend, docomo-ui, db и соответствующий Compose-файл. Инструкция разделяет среду разработки и промышленную эксплуатацию; их настройки не следует смешивать.

## 2. Подготовка хоста

### 2.1. Необходимые средства

| Средство | Где требуется |
| --- | --- |
| Docker Engine и Docker Compose | На хосте разработки и промышленном сервере |
| Доступ к реестрам образов и пакетов | Для сборки и получения зависимостей внутри образов |
| Node.js и pnpm | На машине разработчика для локального frontend; в production — внутри сборочного образа |
| Python 3.13 и uv | В образе backend, задаются Dockerfile |
| PostgreSQL 16 и Redis | В контейнерах из образов, указанных в Compose |

Проверьте Docker:

```sh
docker --version
docker compose version
```

Требования к CPU, RAM и дисковой подсистеме определяются по результатам нагрузочного тестирования исходя из условий эксплуатации и ожидаемого профиля нагрузки, предоставленных эксплуатирующей стороной. При расчёте дискового пространства необходимо предусмотреть место для образов, данных БД, журналов и резервных копий.

### 2.2. Адреса и постоянные данные

| Назначение | Адрес / размещение |
| --- | --- |
| БД для backend внутри сети Compose | docomo-postgres:5432 |
| API для браузера разработчика | http://localhost:8010 |
| Backend внутри контейнера | Порт 8000 |
| Frontend | Порт 3000; локальный процесс при разработке, контейнер в production |
| Публикация БД на хост | 5442 в dev, 5432 в prod; backend эти порты не использует |
| Данные PostgreSQL на хосте | db/pgdata |
| Backend в контейнере | /app, исходники смонтированы из backend |

В DATABASE_URL нельзя использовать localhost или порт 5442: внутри контейнера localhost обозначает сам контейнер backend. Публикация БД на хост нужна только для внешних подключений; административные операции из этой инструкции выполняются через контейнер PostgreSQL.

Dev и prod Compose используют одинаковые container_name и каталог db/pgdata. Не запускайте их одновременно на одном хосте и не используйте один каталог данных для независимых сред. Разделите хосты или подготовьте изолированные конфигурации.

## 3. Файлы окружения

### 3.1. PostgreSQL

Для разработки подготовьте db/.env.local, для production — db/.env.prod:

```dotenv
POSTGRES_USER=admin
POSTGRES_PASSWORD=CHANGE_ME_DATABASE_PASSWORD
POSTGRES_DB=docomo_db
```

Замените пароль собственным секретом. Имена admin и docomo_db соответствуют healthcheck в текущем Compose. POSTGRES_* инициализируют только новую БД; изменение файла не меняет пароль существующей учетной записи PostgreSQL.

### 3.2. Backend

Оба текущих Compose-файла подключают .env.{local|prod}. Значения ENVIRONMENT и cookie-настроек задаются для выбранной среды. Compose передает содержимое файла в окружение контейнера.

Пример backend/.env.local для разработки:

```dotenv
APP_NAME=Docomo API
APP_VERSION=0.1.0
ENVIRONMENT=development
DEBUG=false
DATABASE_URL=postgres://admin:CHANGE_ME_DATABASE_PASSWORD@docomo-postgres:5432/docomo_db
CORS_ORIGINS=http://localhost:3000
CORS_ALLOW_CREDENTIALS=true
AUTH_SESSION_SECRET=CHANGE_ME_LONG_RANDOM_SECRET
AUTH_SESSION_TTL_SECONDS=604800
AUTH_COOKIE_NAME=docomo_session
AUTH_COOKIE_SECURE=false
AUTH_COOKIE_SAMESITE=lax
AUTH_BOOTSTRAP_ADMIN_LOGIN=admin
AUTH_BOOTSTRAP_ADMIN_PASSWORD=CHANGE_ME_ADMIN_PASSWORD
LOG_LEVEL=INFO
LOG_FORMAT=json
LOG_DIR=logs
LOG_RETENTION_DAYS=30
LOG_FILE_NAME=app.log
```

Замените значения CHANGE_ME. Пароль БД должен совпасть с настройками PostgreSQL; специальные символы в пароле кодируются для URL. После сборки backend случайный секрет можно получить внутри одноразового контейнера:

```sh
docker compose -f docker-compose-dev.yml run --rm --no-deps docomo-backend python -c 'import secrets; print(secrets.token_urlsafe(48))'
```

Команда не запускает приложение и не требует подключения к БД. Внесите результат в AUTH_SESSION_SECRET. Для production после сборки образа используется та же команда с docker-compose-prod.yml.

Для production установите ENVIRONMENT=production, AUTH_COOKIE_SECURE=true и CORS_ORIGINS с фактическим HTTPS-адресом frontend. При false для Secure в production сервер отклоняет конфигурацию. Организуйте HTTPS на входе в систему и согласуйте SameSite с размещением frontend и API.

### 3.3. Frontend

При разработке создайте frontend/.env.local:

```dotenv
NEXT_PUBLIC_BACKEND=http://localhost:8010
```

Для промышленной сборки используйте frontend/.env.production с публичным HTTPS-адресом API. NEXT_PUBLIC_BACKEND — адрес, доступный браузеру. Имя docomo-backend в Docker-сети не подходит в качестве браузерного адреса. Значение встраивается при сборке frontend; смена env-файла уже запущенного контейнера не заменяет пересборку.

## 4. Запуск среды разработки

### 4.1. Сборка и запуск инфраструктуры

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

```sh
docker compose -f docker-compose-dev.yml config --quiet
docker compose -f docker-compose-dev.yml up -d
docker compose -f docker-compose-dev.yml ps
```

Дождитесь состояния healthy у PostgreSQL. При ошибке смотрите журналы контейнера. Python и зависимости backend устанавливаются внутри Docker-образа.

### 4.2. Миграции и запуск backend

До первого запуска приложения примените существующие миграции в одноразовом контейнере сервиса backend:

```sh
docker compose -f docker-compose-dev.yml run --rm --no-deps docomo-backend uv run aerich upgrade
docker compose -f docker-compose-dev.yml run --rm --no-deps docomo-backend uv run aerich heads
docker compose -f docker-compose-dev.yml up -d docomo-backend
docker compose -f docker-compose-dev.yml logs --tail=100 docomo-backend
```

Ключ --no-deps используется после отдельного запуска и проверки БД. Команда run наследует настройки, сеть, рабочий каталог и монтирования сервиса, но выполняет указанную команду вместо запуска API. Повторно генерировать начальную миграцию не нужно. Startup приложения подключает ORM, но не создает и не изменяет таблицы.

Backend доступен на http://localhost:8010; для development документация API находится по адресу http://localhost:8010/docs. В Dockerfile.dev включена перезагрузка при изменении кода.

### 4.3. Локальный frontend — только для разработки

В dev Compose сервис frontend закомментирован. На машине разработчика установите Node.js и pnpm; в проекте указаны Node.js 22.13.1 в Dockerfile frontend и pnpm 10.11.0 в package.json.

В каталоге docomo-ui выполните:

```sh
pnpm install --frozen-lockfile
pnpm build
```

Затем в каталоге frontend:

```sh
pnpm install --frozen-lockfile
pnpm dev
```

Frontend использует file:../docomo-ui, поэтому библиотека собирается первой и соседнее расположение каталогов сохраняется. Откройте http://localhost:3000/login. Backend и БД при этом продолжают работать в Docker.

### 4.4. Начальный администратор

При запуске backend с bootstrap-параметрами приложение создает или обновляет администратора и назначает роль admin. После успешного входа удалите AUTH_BOOTSTRAP_ADMIN_PASSWORD из env-файла и пересоздайте контейнер:

```sh
docker compose -f docker-compose-dev.yml up -d --no-deps --force-recreate docomo-backend
```

Обычный restart не перечитывает окружение из измененного env-файла. Оставленный bootstrap-пароль применяется повторно при старте и может вернуть прежний пароль администратора. Для production используйте аналогичную команду с production Compose-файлом.

## 5. Промышленная установка: все сервисы в Docker

### 5.1. Подготовка контейнерной поставки

Целевая схема — контейнеры docomo-postgres, docomo-redis, docomo-backend и docomo-frontend. Прямой запуск backend или frontend на промышленном хосте не предусмотрен.

Production Compose использует контекст сборки из корня репозитория и frontend/Dockerfile.prod. В образе pnpm 10.11.0 устанавливает зависимости обоих пакетов с --frozen-lockfile: сначала собирается docomo-ui, затем устанавливается и собирается frontend. Локальные node_modules, dist и .next исключены из контекста через корневой .dockerignore.

В next.config.ts включен output: standalone, корень трассировки зависимостей — корень репозитория. Итоговый образ содержит standalone-сервер, public и .next/static; запускается node frontend/server.js от непривилегированного пользователя.

Перед сборкой создайте frontend/.env.production с публичным адресом API (см. подраздел 3.3). Compose читает его по пути ./frontend/.env.production. Этот же файл используется при сборке: при изменении NEXT_PUBLIC_BACKEND необходимо пересобрать образ и пересоздать контейнер.

Production Compose также монтирует backend в /app и отдельный том в /app/.venv. Учитывайте оба монтирования при обновлении исходников и зависимостей. Redis присутствует в составе Compose; использование его основными прикладными операциями текущим кодом не подтверждено.

### 5.2. Сборка, миграции и запуск

Подготовьте db/.env.prod, backend/.env.local с production-настройками и frontend/.env.production. После выполнения условий подраздела 5.1:

```sh
docker compose -f docker-compose-prod.yml config --quiet
docker compose -f docker-compose-prod.yml up -d
docker compose -f docker-compose-prod.yml ps
```

После перехода PostgreSQL в healthy:

```sh
docker compose -f docker-compose-prod.yml run --rm --no-deps docomo-backend uv run aerich upgrade
docker compose -f docker-compose-prod.yml run --rm --no-deps docomo-backend uv run aerich heads
docker compose -f docker-compose-prod.yml up -d docomo-backend docomo-frontend
docker compose -f docker-compose-prod.yml ps
docker compose -f docker-compose-prod.yml logs --tail=100 docomo-backend docomo-frontend
```

Зависимости backend устанавливаются в образе Docker, сборка docomo-ui и frontend выполняется в сборочном контейнере. На хосте нужен Docker. В продуктивной среде /docs, /redoc и /openapi.json отключены. Для доступа пользователей используйте настроенный HTTPS-адрес; опубликованные порты 8010 и 3000 подключаются к принятой схеме обратного прокси.

## 6. Эксплуатационные команды

Примеры для production, в разработке замените имя Compose-файла на docker-compose-dev.yml:

```sh
docker compose -f docker-compose-prod.yml ps
docker compose -f docker-compose-prod.yml logs --tail=100 docomo-backend
docker compose -f docker-compose-prod.yml exec docomo-backend sh
docker compose -f docker-compose-prod.yml exec docomo-backend uv run aerich heads
docker compose -f docker-compose-prod.yml exec docomo-postgres pg_isready -U admin -d docomo_db
```

Exec применяется к уже работающему контейнеру, run — для одноразовой команды, в том числе до запуска API. Изменения env-файлов вводятся пересозданием контейнера через up -d --force-recreate. Остановка сервисов выполняется через docker compose stop, последующий запуск — через up -d. Данные db/pgdata не удаляйте при штатном обслуживании.

Корневые make startLocal, stopLocal, logsLocal и shBackendLocal вызывают dev Compose. При первом запуске сначала нужны миграции, используйте команды Aerich через Compose, приведенные выше.

## 7. Проверка установки

1. Убедитесь, что PostgreSQL healthy, миграции завершились без ошибки, контейнер backend запущен.
2. Для разработки откройте http://localhost:8010/docs; для промышленной среды проверьте API через пользовательские операции.
3. Выполните вход во frontend и откройте /admin/access.
4. Создайте тестовую роль и пользователя.
5. В /admin/constructor создайте форму с основной схемой и выдайте роли read и write.
6. Под тестовым пользователем создайте запись и повторно откройте ее.
7. Проверьте выход и требование повторной авторизации.
8. Просмотрите журналы контейнеров на ошибки соединения, миграций и авторизации.

Это приемочная процедура; подготовка документов не означает, что она уже выполнена на инфраструктуре заказчика.

## 8. Обновление контейнерной установки

Сохраните резервную копию БД, конфигурацию и идентификатор предыдущего выпуска. Проверьте обновление и восстановление на отдельном Docker-стенде. В согласованное окно остановите прикладные контейнеры, затем обновите исходники: в текущем Compose backend использует bind mount, поэтому замена исходников влияет на контейнер напрямую.

После обновления исходников соберите новые образы. При работающей БД выполните миграции через одноразовый контейнер backend, затем пересоздайте прикладные контейнеры. Учтите отдельный том /app/.venv: backend запускается через uv run, который синхронизирует окружение внутри контейнера с зависимостями проекта. Команды после остановки контейнеров и обновления исходного кода:

```sh
docker compose -f docker-compose-prod.yml build docomo-backend docomo-frontend
docker compose -f docker-compose-prod.yml run --rm --no-deps docomo-backend uv run aerich upgrade
docker compose -f docker-compose-prod.yml up -d --force-recreate docomo-backend docomo-frontend
```

При изменении зависимостей uv run также выполняет их синхронизацию при старте. Если контейнер не запускается, анализируйте журналы и состояние его окружения. Повторите проверку из раздела 7. Не удаляйте БД для исправления сборки приложения. Откат схемы выполняется по проверенному плану восстановления, а не только заменой образа.

## 9. Типовые ошибки

| Признак | Что проверить |
| --- | --- |
| Нет DATABASE_URL | Файл backend/.env.local, env_file выбранного сервиса и пересоздание контейнера |
| Backend не соединяется с БД | docomo-postgres:5432, общая Docker-сеть, пароль и healthy |
| Таблица не существует | Aerich upgrade в контейнере до запуска API |
| Вход не сохраняется | CORS, Secure/SameSite, HTTPS и браузерный URL API |
| Браузер не видит API | В разработке NEXT_PUBLIC_BACKEND=http://localhost:8010 |
| После редактирования env значение прежнее | Пересоздание контейнера; для NEXT_PUBLIC_BACKEND — пересборка frontend |
| Не найден @docomo/ui | При разработке — соседний каталог и dist; в production — состав контекста и сборочного образа |
| Нет /docs | Включен только при ENVIRONMENT=development |
| Production backend не запускается | AUTH_COOKIE_SECURE=true и журналы контейнера |
| Не собирается frontend-образ | Предварительные условия подраздела 5.1 |
