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

Это руководство проведёт вас от нуля до работающего бэкенда Apostol CRM с 418 REST API эндпоинтами, аутентификацией OAuth 2.0 и движком рабочих процессов.

Предварительные требования

Требование	Примечание
Docker и Docker Compose	Рекомендуется для быстрого старта
Git	Для клонирования репозитория

Для сборки из исходников дополнительно понадобятся:

Требование	Версия	Примечание
Компилятор C++	GCC 12+ или Clang 16+	Обязательна поддержка C++20
CMake	3.25+	Система сборки
PostgreSQL	12+	Сервер базы данных
OpenSSL	любая	TLS, JWT, SMTP
libcurl	любая	HTTP-клиент
zlib	любая	Сжатие логов

Debian/Ubuntu:

sudo apt-get install build-essential libssl-dev libcurl4-openssl-dev \
    libpq-dev zlib1g-dev make cmake gcc g++

Быстрый старт с Docker

Самый быстрый способ получить рабочее окружение:

git clone --recurse-submodules https://github.com/apostoldevel/apostol-crm.git
cd apostol-crm/backend
./docker-build.sh
./docker-up.sh

Запускается пять сервисов: PostgreSQL 18, PgBouncer, Nginx, PgWeb и Backend.

URL	Что получаете
localhost:8080	Фронтенд
localhost:8080/docs	Swagger UI (418 эндпоинтов)
localhost:8081	PgWeb -- администрирование БД

Учётные данные по умолчанию: admin / admin

Остановка и сброс:

./docker-down.sh           # остановить все сервисы
./docker-new-database.sh   # пересоздать том PostgreSQL (деструктивно)

Сборка из исходников

Клонирование и сборка

git clone --recurse-submodules https://github.com/apostoldevel/apostol-crm.git
cd apostol-crm/backend
./configure
cmake --build cmake-build-release --parallel $(nproc)
sudo cmake --install cmake-build-release

Настройка базы данных

# 1. Настройте пароли
echo '*:*:*:kernel:kernel' >> ~/.pgpass
echo '*:*:*:admin:admin'   >> ~/.pgpass
echo '*:*:*:daemon:daemon' >> ~/.pgpass
chmod 600 ~/.pgpass

# 2. Добавьте в postgresql.conf и перезапустите PostgreSQL:
#    search_path = '"$user", kernel, public'

# 3. Инициализация
cd db/
./runme.sh --init

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

sudo service apostol-crm start

Режим разработки

Для локальной разработки без установки в систему:

./configure --debug
cmake --build cmake-build-debug --parallel $(nproc)
mkdir -p logs
./cmake-build-debug/apostol-crm -p . -c conf/default.json

Первый API-запрос

После запуска сервера проверьте его работу:

# Проверка работоспособности
curl http://localhost:4977/api/v1/ping
# {"ok": true}

# Аутентификация (получение токена сессии)
curl -X POST http://localhost:4977/oauth2/token \
  -d 'grant_type=password&username=admin&password=admin&client_id=web'
# {"access_token": "eyJ...", "token_type": "Bearer", ...}

# Использование токена для получения списка клиентов
curl http://localhost:4977/api/v1/client/list \
  -H 'Authorization: Bearer eyJ...'

При работе через Docker используйте порт 8080 вместо 4977 (прокси Nginx).

Команды базы данных

Все команды выполняются из каталога db/:

Команда	Действие
`./runme.sh --update`	Безопасно: обновляет только процедуры и представления
`./runme.sh --patch`	Обновляет таблицы + процедуры + представления
`./runme.sh --install`	Деструктивно: пересоздаёт БД с начальными данными
`./runme.sh --init`	Деструктивно: первичная настройка (создание пользователей + установка)

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

Основной файл конфигурации -- conf/default.json:

{
  "prefix": ".",
  "server": {
    "listen": "127.0.0.1",
    "port": 4977
  },
  "module": {
    "AuthServer": { "enable": true },
    "AppServer": { "enable": true },
    "FileServer": { "enable": true },
    "WebSocketAPI": { "enable": true }
  },
  "postgres": {
    "connect": true,
    "worker": { "user": "daemon" },
    "helper": { "user": "apibot" },
    "kernel": { "user": "kernel" }
  }
}

Следующие шаги

Архитектура -- как C++-сервер и движок PostgreSQL работают вместе
Создание сущности -- добавление собственных бизнес-объектов
Рабочие процессы -- описание собственных состояний и переходов
REST-эндпоинты -- публикация сущностей через REST API
Справочник API -- все 418 эндпоинтов