Первоначальная настройка
Это руководство проведёт вас через развёртывание Cuento с нуля — от требований до полностью настроенного форума, готового к игре. Процесс занимает около 30 минут и не требует ручной работы с сервером.
Что нужно перед началом
- VPS под управлением Ubuntu 22.04 с не менее 1 ГБ ОЗУ. Подойдёт любой провайдер (DigitalOcean, Hetzner, Linode и др.). На сервер должен быть доступ по SSH с аутентификацией по паролю.
- Доменное имя, указывающее на IP вашего VPS. Установщик настраивает HTTPS автоматически — домен должен корректно резолвиться до запуска установщика.
- Аккаунт GitHub. Установщик форкает исходные репозитории Cuento на ваш аккаунт. Именно через это вы получаете обновления и работает CI/CD-деплой форума.
Шаг 1 — Установите Cuento CLI
Скачайте бинарник CLI для вашей ОС со страницы релизов Cuento и сделайте его исполняемым:
# macOS
chmod +x cuento-cli-macos
./cuento-cli-macos
CLI не имеет флагов. Всё управляется через интерактивные меню.
Шаг 2 — Запустите мастер установки
Выберите Create new project в главном меню. Мастер сохраняет прогресс после каждого шага — если процесс прерван, перезапустите его и он продолжит с того же места.
Мастер запросит:
- Персональный токен GitHub с правами
repoиworkflow(создайте его в GitHub → Settings → Developer settings → Personal access tokens) - Ваш логин GitHub
- IP-адрес VPS, SSH-имя пользователя и пароли
- Доменное имя
- Учётные данные базы данных (вы выбираете пароли — мастер создаёт базу данных сам)
Что мастер устанавливает на сервере
Мастер полностью автоматизирует подготовку сервера:
| Компонент | Роль |
|---|---|
| MariaDB | База данных |
| Caddy | HTTPS обратный прокси — сертификаты получаются и продлеваются автоматически |
| Sonic | Движок полнотекстового поиска |
| Qdrant | Семантический/векторный поиск |
| Backend-сервис | Приложение Cuento на Go, работающее как systemd-сервис |
Брандмауэр настраивается на разрешение только портов 22, 80 и 443. После завершения работы мастера сервер не нужно трогать вручную.
Как работают деплои после настройки
Мастер настраивает GitHub Actions на ваших форкнутых репозиториях. С этого момента каждый push в ветку release форка автоматически собирает и деплоит обновление на сервер. SSH-доступ к серверу для деплоев больше не нужен.
Шаг 3 — Дождитесь первого деплоя
После завершения мастера первый деплой-пайплайн запускается автоматически. Это занимает несколько минут. Следить за ходом можно в вашем GitHub-репозитории на вкладке Actions.
После завершения откройте ваш домен — должен отобразиться форум Cuento.
Шаг 4 — Создайте первый admin-аккаунт
После первого деплоя в базе данных нет настоящих аккаунтов — только два встроенных системных пользователя: guest (ID 0) и The Nameless One (ID 1). Используйте CLI для создания admin-аккаунта:
- Запустите CLI и выберите Add user.
- Введите логин и пароль.
- На вопрос Make this user an admin? ответьте да. Аккаунт получит роли
userиadmin.
CLI напрямую подключается к базе данных вашего сервера и создаёт аккаунт. Поскольку ID 0 и 1 заняты, первый созданный аккаунт получает ID 2.
Шаг 5 — Установите суперпользователя
Суперпользователь — это один конкретный аккаунт с привилегиями выше роли администратора. В CLI выберите Set superuser и введите ID пользователя (2 для первого созданного аккаунта).
Это записывает переменную окружения SUPERUSER_ID в backend-сервис и перезапускает его. Суперпользователь не хранится в базе данных, поэтому сохраняется при восстановлении базы и меняется только при повторном запуске этой команды.
Только суперпользователь может:
- настраивать ИИ-модели
- запускать резервное копирование в Google Drive и управлять им
- просматривать и изменять секретные настройки, например API-ключи
Кроме того, для суперпользователя не проверяется таблица прав эндпоинтов, поэтому он может вызывать любые административные эндпоинты даже до импорта прав. Правила доступа к подфорумам на него распространяются — доступ выдаётся для каждого подфорума, как и любому другому пользователю (шаг 8).
Шаг 6 — Импортируйте права доступа по умолчанию
Система прав доступа Cuento контролирует, какие роли пользователей могут вызывать какие API-эндпоинты. Значения по умолчанию нужно загрузить в базу данных один раз после первого деплоя.
В CLI выберите Import default permissions. CLI загрузит актуальный permissions.csv из upstream-репозитория и загрузит его в вашу базу данных с INSERT IGNORE — существующие настройки никогда не перезаписываются.
Эту операцию нужно повторять после обновлений, добавляющих новые эндпоинты.
Шаг 7 — Настройте форум
Войдите в форум по вашему домену, затем перейдите на /admin. Административная панель организована по разделам:
Общие настройки — укажите название форума, описание и язык по умолчанию. Эти данные отображаются в шапке сайта и в заголовке вкладки браузера.
Подфорумы — создайте структуру подфорумов. У каждого могут быть собственные правила доступа — по умолчанию все подфорумы закрыты, и вы должны явно предоставлять доступ пользователям.
Пользователи — управляйте регистрациями, назначайте роли и предоставляйте доступ к подфорумам. Три роли: гость (неаутентифицированный), пользователь (зарегистрированный участник) и администратор.
Функции — опциональные модули: ИИ, дайджест игры, валюта, рейтинг постов. По умолчанию все отключены.
ИИ — настройте пул моделей, если нужны AI-функции. Подробнее — в Настройка ИИ.
Шаг 8 — Предоставьте доступ к подфорумам
Новые зарегистрированные пользователи не видят ни одного подфорума, пока вы не предоставите им доступ. Это сделано намеренно — модель прав доступа Cuento работает по принципу явного разрешения на уровне подфорума, независимо от глобальной роли.
Для предоставления доступа перейдите в Администрирование → Подфорумы → [название подфорума] → Права доступа и добавьте пользователя. Можно выдать права только на чтение или полные права на постинг.
Поддержание форума в актуальном состоянии
Когда выходит новая версия Cuento, запустите Update из главного меню CLI. Он:
- Покажет, что изменилось с вашего последнего деплоя
- Сгенерирует и покажет миграцию базы данных
- Применит миграцию пошагово (с автоматическим откатом при сбое)
- Смержит обновление в ваш форк и запустит деплой
Вы всегда контролируете процесс — ни одно обновление не применяется без вашего подтверждения.