magistr/STARTUP_GUIDE.md

Инструкция запуска Magistr

Ниже — минимальный порядок действий. Подробности по инфраструктуре и секретам находятся в docs/INFRASTRUCTURE.md и docs/SECURITY_RUNBOOK.md.

1. Локальный запуск

Нужны Git, Docker Engine, Docker Compose и запущенный Caddy из ../сaddy-proxy/.

1. В корне проекта создайте локальный файл настроек:

   cp .env.example .env
   openssl rand -base64 36   # значение POSTGRES_PASSWORD
   openssl rand -base64 48   # значение JWT_SECRET
   

   Вставьте полученные значения в .env. Файл .env не коммитьте.

2. Один раз создайте общую Docker-сеть, затем запустите Caddy и Magistr:

   docker network inspect proxy >/dev/null 2>&1 || docker network create proxy
   docker compose -f ../сaddy-proxy/compose.yaml up -d
   docker compose config --quiet
   docker compose up -d --build
   docker compose ps
   

3. Откройте https://localhost (http://localhost перенаправит на HTTPS). Проверьте backend через Caddy:

   curl -kfsS https://localhost/actuator/health/readiness
   

   Если браузер не доверяет локальному сертификату Caddy, на CachyOS/Arch выполните:

   docker cp caddy:/data/caddy/pki/authorities/local/root.crt /tmp/caddy-local-root.crt
   sudo trust anchor --store /tmp/caddy-local-root.crt
   

   До установки проверьте SHA-256 отпечаток командой openssl x509 -in /tmp/caddy-local-root.crt -noout -fingerprint -sha256, затем полностью перезапустите браузер.

   Для первого локального входа: admin / admin. Эти данные предназначены только для разработки.

4. Если запуск не удался:

   docker compose logs --tail=200 backend db frontend
   

   Полный локальный сброс БД выполняется командой docker compose down -v, но она удалит все локальные данные. Обычная остановка без удаления данных: docker compose down.

2. Первый запуск в production

1. Подготовьте K3s/Kubernetes-кластер и убедитесь, что kubectl get nodes работает. PostgreSQL в текущие манифесты не входит: заранее создайте доступную из кластера БД для каждого университета. Пользователь БД должен иметь права на создание и изменение схемы — Flyway применит V1__init.sql автоматически.

2. Настройте DNS для magistr.zuev.company и остальных tenant-доменов на публичный reverse proxy/Ingress. В текущем ../k8s/ingress.yaml нет секции TLS: для HTTPS нужно настроить внешний Caddy с сертификатом либо добавить cert-manager/TLS в кластер.

3. Создайте namespace и четыре обязательных Secret по docs/SECURITY_RUNBOOK.md:

   • app-secret: JWT_SECRET, POSTGRES_USER, POSTGRES_PASSWORD;
   • tenants-secret: файл tenants.json;
   • otel-postgres-secret: подключения Collector к БД;
   • gitea-registry: доступ к приватным Docker-образам.

   Для magistr.zuev.company запись в tenants.json должна иметь "domain": "magistr" и реальный JDBC URL. Не сохраняйте значения Secret в Git или логах.

4. В Gitea Actions добавьте секреты ZUEV_TOKEN (доступ к registry) и KUBECONFIG_DATA (kubeconfig в Base64). Push в main соберёт, проверит и опубликует образы. При самом первом запуске автоматический deploy может ещё не найти Deployment — возьмите два опубликованных digest из CI/registry и выполните bootstrap вручную:

   export BACKEND_IMAGE_REF='gitea.zuev.company/zuev/magistr-backend@sha256:<digest>'
   export FRONTEND_IMAGE_REF='gitea.zuev.company/zuev/magistr-frontend@sha256:<digest>'
   K8S_DIR=../k8s bash scripts/check-production-secrets.sh
   K8S_DIR=../k8s bash scripts/check-artifact-pinning.sh
   kubectl kustomize ../k8s >/dev/null
   bash ../k8s/deploy.sh apply
   

5. Проверьте результат:

   bash ../k8s/deploy.sh status
   kubectl rollout status deployment/backend -n magistr --timeout=300s
   kubectl logs -n magistr -l app=backend --tail=200
   curl -fsS https://magistr.zuev.company/
   

   После первого входа немедленно смените/отключите все тестовые пароли из V1__init.sql. Следующие push в main CI/CD сможет развёртывать автоматически.

3. Что могу выполнить я

По вашей команде я могу подготовить .env, запустить и диагностировать локальный Compose, проверить/исправить код и манифесты, прогнать тесты и dry-run Kubernetes, а при доступном kubectl — проверить состояние кластера.

Без вас я не могу получить реальные пароли и токены, настроить DNS/сертификаты у внешнего провайдера или войти в Gitea/Kubernetes, если доступы не предоставлены. Production deploy, ротацию Secret и удаление БД я не выполняю без отдельного явного разрешения: это меняет внешнюю систему и может прервать работу либо уничтожить данные.