Локальная установка

Запустите Cuento на своём компьютере для локальной разработки — от пустого Docker-тома до работающего форума с учётной записью администратора и суперпользователя. Вам понадобятся Docker, Node.js и npm.

1. Скачайте репозитории

Бэкенд и фронтенд Cuento находятся в отдельных репозиториях. Склонируйте оба:

git clone https://github.com/kate-makarova/cuento-backend
git clone https://github.com/kate-makarova/cuento-frontend

2. Переключите оба репозитория на release

Активная разработка ведётся в ветке release. Ветка main может отставать на месяцы — в ней могут отсутствовать целые подсистемы (суперпользователь, Sonic, Qdrant) и значительная часть таблицы прав. Всегда собирайте новый экземпляр из release, причём в обоих репозиториях:

cd cuento-backend
git fetch origin && git checkout release && git merge --ff-only origin/release
cd ../cuento-frontend
git fetch origin && git checkout release && git merge --ff-only origin/release

3. Запустите контейнеры бэкенда

В директории cuento-backend запустите сервисы:

cd cuento-backend
docker compose up -d --build db sonic qdrant app

Это поднимет Go API на порту 8080, MCP-сервер на порту 8081, MariaDB на порту 3306, Sonic и Qdrant.

В compose-файле также описан сервис caddy. Локально он не нужен: он отдаёт страницу-заглушку из cuento-backend/frontend/, а не приложение Angular, и занимает порты 80 и 443.

Если на macOS команда docker не найдена, но Docker Desktop установлен, запустите его командой open -a Docker и добавьте его CLI в путь:

export PATH="/Applications/Docker.app/Contents/Resources/bin:$PATH"

4. Загрузите схему базы данных

Docker Compose создаёт пустую базу cuento — схема автоматически не загружается. Когда MariaDB начнёт принимать подключения, импортируйте её из src/Install/default_tables.sql:

docker compose exec -T db mariadb -uuser -ppassword cuento \
  < src/Install/default_tables.sql

Выполняйте это только один раз и только для пустой базы. Текущий образ MariaDB содержит только клиент mariadb — команды с mysql не сработают.

Схема создаёт три роли (1 guest, 2 user, 3 admin) и двух системных пользователей: guest (id 0) и The Nameless One (id 1).

5. Импортируйте права доступа

В новой базе нет прав доступа, поэтому любой запрос к API будет отклонён. Права по умолчанию находятся в src/Install/permissions.csv — по одной строке на право в формате role_id,type,permission. Загрузите их так же, как это делает Cuento CLI, — по одному INSERT IGNORE на строку:

awk -F, 'NR>1 && NF>=3 {printf "INSERT IGNORE INTO role_permission (role_id, type, permission) VALUES (%d, %d, '"'"'%s'"'"');\n", $1, $2, $3}' \
  src/Install/permissions.csv | tr -d '\r' \
  | docker compose exec -T db mariadb -uuser -ppassword cuento

Благодаря INSERT IGNORE команду можно запускать повторно — делайте это каждый раз, когда в CSV появляются новые эндпоинты. Дубликаты строк в CSV отбрасываются первичным ключом (role_id, permission), поэтому число вставленных записей может быть немного меньше числа строк.

Проверьте, что гостю доступен публичный эндпоинт:

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/active-topics   # ожидается 200

6. Установите Node.js и npm

Для фронтенда требуется Node.js 24 LTS (Angular 22 нужен ^22.22.3, ^24.15 или 26 и выше). Если у вас его нет, скачайте с nodejs.org или используйте менеджер версий nvm:

nvm install 24
nvm use 24

7. Запустите фронтенд

В директории cuento-frontend установите зависимости и запустите сервер разработки:

cd cuento-frontend
npm install
npm start

Сервер разработки Angular запустится по адресу http://localhost:4200. В режиме разработки приложение обращается к API напрямую по адресу http://localhost:8080 (бэкенд разрешает кросс-доменные запросы).

Запускайте npm install заново после каждого переключения веток — node_modules из другой ветки могут содержать другую версию Angular.

8. Создайте первую учётную запись

Откройте http://localhost:4200/register и зарегистрируйтесь. Новые учётные записи получают только роль user.

Поскольку id 0 и 1 заняты системными пользователями, первая настоящая учётная запись получает id 2. Проверьте:

docker compose exec -T db mariadb -uuser -ppassword cuento \
  -e 'SELECT id, username FROM users WHERE id > 1'

9. Сделайте учётную запись администратором

Добавьте учётной записи роль admin (id 3):

docker compose exec -T db mariadb -uuser -ppassword cuento \
  -e 'INSERT IGNORE INTO user_role (user_id, role_id) VALUES (2, 3)'

10. Сделайте учётную запись суперпользователем

Суперпользователь — отдельный уровень выше администратора. Он открывает функции, которые не может выдать ни одна роль:

  • настройка ИИ-моделей (Controllers/ai_model.go)
  • резервные копии в Google Drive (Controllers/backup.go)
  • просмотр и изменение настроек с пометкой needs_superuser — API-ключи и подобные секреты (Controllers/settings.go)

Кроме того, для суперпользователя не проверяется таблица прав эндпоинтов в Middlewares/permissions.go. Доступ к подфорумам проверяется отдельно.

Суперпользователь не хранится в базе данных. Бэкенд один раз при запуске читает переменную окружения SUPERUSER_ID. В docker-compose.yml она равна 3, что не совпадает с первой учётной записью, поэтому переопределите её локально в файле docker-compose.override.yml рядом с compose-файлом:

services:
  app:
    environment:
      - SUPERUSER_ID=2

Затем пересоздайте контейнер бэкенда, чтобы он подхватил новое значение:

docker compose up -d app
docker compose exec -T app printenv SUPERUSER_ID   # ожидается 2

Файл переопределения не игнорируется git — не коммитьте его.

Наконец, выйдите из учётной записи и войдите снова, чтобы новая роль вступила в силу. Панель администратора находится по адресу http://localhost:4200/admin.

Запуск тестов бэкенда

Тесты обработчиков в cuento-backend/test/ работают с настоящей базой MariaDB cuento_test в том же контейнере db, что и база для разработки. Создайте её один раз:

docker compose exec -T db mariadb -uroot -prootpassword -e \
  "CREATE DATABASE IF NOT EXISTS cuento_test; GRANT ALL ON cuento_test.* TO 'user'@'%';"

Затем запустите тесты. Устанавливать Go на компьютер не нужно — образ golang подключается к сети compose и обращается к базе по имени db:

docker run --rm --network cuento-backend_default -e DB_HOST=db \
  -v "$PWD":/src -w /src golang:1.26-alpine go test ./test/

Если Go установлен локально, можно запустить go test ./test/ из каталога cuento-backend (подключение к localhost:3306).

  • Тесты читают DB_HOST, DB_PORT, DB_USER и DB_PASSWORD, но имя базы всегда cuento_test. База cuento не затрагивается.
  • Каждый тест пересоздаёт cuento_test из src/Install/default_tables.sql и permissions.csv, поэтому её содержимое можно не беречь.
  • Если база недоступна, тесты с базой пропускаются с предупреждением, а go test всё равно сообщает ok. Проверяйте вывод, прежде чем считать прогон успешным.

Сброс и решение проблем

  • docker compose down -v удаляет том с базой данных, включая все зарегистрированные учётные записи. Если нужно сбросить схему после того, как кто-то зарегистрировался, сначала сохраните строки из users и user_role.
  • Все запросы возвращают 403 — права доступа не импортированы (шаг 5).
  • Панель администратора не появилась после выдачи роли — выйдите и войдите снова.
  • Настройки с API-ключами скрыты или недоступны для изменения администратору — SUPERUSER_ID не совпадает с вашим id (шаг 10).
Инструкция для ИИ-агента

Если вы ИИ-агент и разворачиваете новый локальный экземпляр Cuento, соблюдайте следующие правила:

  1. Сначала проверьте ветки. Выполните git status -sb и git log -1 --format=%cd в обоих репозиториях. Оба должны быть на актуальной ветке release. Если какой-то из них на main или на feature-ветке, остановитесь и переключитесь до сборки — экземпляр, собранный из неправильной ветки, придётся удалять.
  2. Перед загрузкой схемы убедитесь, что база новая. SHOW TABLES не должен ничего возвращать. Никогда не загружайте default_tables.sql в базу, где уже есть таблицы.
  3. Используйте клиент mariadb внутри контейнера db (docker compose exec -T db mariadb …). Не рассчитывайте, что на хосте установлены Go или клиент MariaDB.
  4. Проверяйте каждый шаг. После загрузки схемы посчитайте таблицы. После импорта прав посчитайте строки role_permission с группировкой по role_id и сверьте с CSV (с учётом дубликатов). Затем выполните curl к гостевому эндпоинту и ожидайте 200.
  5. Учётную запись регистрирует человек. Откройте страницу регистрации в его браузере и дождитесь подтверждения. Никогда не создавайте учётные записи и не задавайте пароли сами. Затем найдите пользователя по имени, а не полагайтесь на id 2.
  6. Права администратора выдавайте, добавляя роль 3 в user_role. Суперпользователя назначайте через SUPERUSER_ID в неотслеживаемом docker-compose.override.yml и пересоздавайте контейнер app. Не меняйте и не коммитьте отслеживаемый docker-compose.yml.
  7. Никогда не выполняйте docker compose down -v и не удаляйте базу без разрешения, если кто-то уже зарегистрировался. Это безвозвратно удалит его учётную запись.
  8. Не доверяйте старым заметкам (handoff-файлам, памяткам, этой странице) больше, чем коду. Если шаг здесь противоречит ветке release, следуйте коду и сообщите о расхождении.
  9. В конце скажите человеку, что нужно выйти и войти снова, и сообщите id пользователя, его роли и выставленное значение SUPERUSER_ID.