Первоначальная настройка

Это руководство проведёт вас через развёртывание 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-аккаунта:

  1. Запустите CLI и выберите Add user.
  2. Введите логин и пароль.
  3. На вопрос 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. Он:

  1. Покажет, что изменилось с вашего последнего деплоя
  2. Сгенерирует и покажет миграцию базы данных
  3. Применит миграцию пошагово (с автоматическим откатом при сбое)
  4. Смержит обновление в ваш форк и запустит деплой

Вы всегда контролируете процесс — ни одно обновление не применяется без вашего подтверждения.