Начало работы

Это руководство охватывает установку, настройку и запуск первого экземпляра Letopis.

Требования

Установка

Готовые бинари

Скачайте архив под свою платформу (linux/darwin/windows, amd64/arm64) со страницы GitHub Releases. В архиве — бинарь letopis, LICENSE, NOTICE, config.example.yaml и docker-compose.deps.yml.

Из исходников

git clone https://github.com/max-trifonov/letopis.git
cd letopis
make build          # создаёт bin/letopis

Бинарь встраивает версию, хэш коммита и дату сборки через ldflags; make build берёт их из git describe автоматически.

Docker

Образ публикуется в ghcr.io/max-trifonov/letopis. Для локальной сборки:

make docker          # тегирует ghcr.io/max-trifonov/letopis:latest

Доступны два compose-варианта:

Dev-стек

docker compose -f docker-compose.dev.yml up --build

Собирает образ из рабочей директории и запускает MongoDB, Redis и сервис вместе.

Production-стек

cp config.example.yaml config.yaml   # отредактируйте перед запуском
docker compose up -d

Использует опубликованный образ. MongoDB и Redis включены в compose-файл для удобства; в продакшне обычно mongodb.uri и redis.addr указывают на управляемую инфраструктуру.

Конфигурация

Letopis настраивается через YAML-файл. Бинарь ищет config.yaml в следующем порядке:

1. Путь, указанный флагом --config (наивысший приоритет)
2. Текущая рабочая директория
3. Директория рядом с бинарём

Конфигурационный файл обязателен — без него сервер не стартует.

После загрузки файла любая переменная окружения LETOPIS_* переопределяет соответствующий ключ:

Минимальная конфигурация

Минимальная production-конфигурация должна задать:

Полный справочник — config.example.yaml.

Запуск сервера

./bin/letopis serve

По умолчанию роль all — HTTP + gRPC + worker в одном процессе. Для продакшна можно разделить:

./bin/letopis serve --role=api     # только HTTP + gRPC
./bin/letopis serve --role=worker  # только async-обработчик событий

Первая запись

# API-ключ из config.yaml
TOKEN=hm_dev_plaintext

# Отправить состояние (сервер вычислит дифф)
curl -s -X POST http://localhost:8080/api/v1/collections/crm.deals/entities/deal-1/state \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"state": {"title": "ООО Ромашка", "amount": 50000, "stage": "prospect"}}'

Ожидаемый ответ (режим durable возвращает 202 с тикетом):

{
  "ticket_id": "tkt_01hx...",
  "status": "accepted"
}

Чтение данных

# Текущее состояние
curl -s http://localhost:8080/api/v1/collections/crm.deals/entities/deal-1/state \
  -H "Authorization: Bearer $TOKEN"

# Полная история
curl -s http://localhost:8080/api/v1/collections/crm.deals/entities/deal-1/history \
  -H "Authorization: Bearer $TOKEN"

Системные эндпоинты

Разработка

make test             # go test -race ./...
make test-integration # требует Docker — интеграционные тесты (testcontainers)
make lint             # golangci-lint + buf lint
make proto            # перегенерация gRPC-биндингов
make bench            # бенчмарки diff/pipeline