Quickstart

Пошаговый запуск проекта с нуля на локальной машине. Документ описывает текущее состояние репозитория, а не target design.

Prerequisites

Инструмент	Версия	Зачем
Docker + Docker Compose v2	последние	compose-стек (infra + web ingress)
Go	1.25+	локальный запуск backend без контейнера
Node.js	22+	Quartz docs build + admin UI
pnpm	10.33+ (через corepack)	admin UI dependencies
Python	3.12+	скрипты docs governance
openssl	любой	self-signed сертификаты для `*.tracium.dev`

Также требуется правка /etc/hosts:

127.0.0.1 tracium.dev docs.tracium.dev api.tracium.dev id.tracium.dev

Без этого локальный ingress не резолвится по именам. Проверить без правки hosts можно через make verify-local-web — он использует curl --resolve.

Шаги

1. Склонировать репозиторий

git clone git@gitlab.com:tracium/main.git tracium
cd tracium

2. Инициализировать env-файлы и сертификаты

make init-env     # создаёт .env, deploy/.env, deploy/auth/.env из *.example
make ssl-init     # генерирует self-signed certs для *.tracium.dev

SHARED_WORKSPACE в deploy/.env должен указывать на абсолютный путь к каталогу с shared/auth (обычно /Users/<you>/projects/shared). Без этого make web-up не соберёт auth.

3. Поднять базовую инфраструктуру

make infra-up      # PG, Redis, Kafka, ES, CH, MinIO, OTel
make infra-status  # проверить, что контейнеры healthy

4. Поднять локальный HTTPS ingress

make web-up        # nginx + docs (Quartz) + api + auth + admin-ui
make verify-local-web

После этого доступны:

https://tracium.dev:4444 — landing placeholder.
https://docs.tracium.dev:4444 — документация (Quartz).
https://api.tracium.dev:4444 — минимальный dev API.
https://id.tracium.dev:4444 — Tracium ID (shared/auth).

5. Опционально: запустить backend вне Docker

cd backend
go run ./cmd/api-server

Полный verify локального окружения:

make verify        # config + docs + backend tests + errorlint

6. Опционально: запустить admin UI в dev-режиме

cd web/admin
pnpm install
pnpm dev

Troubleshooting

Типичные проблемы и их причины — в ../../deploy/docker/README.md (секция Troubleshooting).

Что дальше

Полное описание deploy-контура: ../40-operations/deployment.md.
Как вести изменения: ../50-processes/contributing.md.
Архитектурные принципы: ../20-architecture/principles.md.
Backend-specific команды: ../../backend/README.md.

Tracium

Разделы