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