Установка и запуск

Окружение игры организуется с помощью Docker.

В рамках этого документа предполагается, что вы знакомы с базовыми концепциями Docker.

Инструкция проверялась под Ubuntu, должна работать для любого популярного linux дистрибутива.

Инструкция должна работать для Windows под WSL — Windows Subsystem for Linux, но не проверялась.

Мы с радостью примем pull requests с уточнениями как документации, так и кода.

Термины и соглашения

Далее будут встречаться некоторые понятия, которые лучше пояснить отдельно.

  • старые сервисы — сервисы игры, разработанные на оригинальном движке. Используют Django, общаются через очереди, реализованы в коде сайта. Отвечают за логику игры.

  • новые сервисы — часть игры, переписанная на микросервисную архитектуру. Использует aiohttp, общается по http, реализованы отдельными модулями.

Установка (для разработки)

Установите Docker и Docker Compose.

Стоит отметить что проект использует Compose V2, больше об этом тут.

git clone https://github.com/Tiendil/the-tale.git

сd ./the-tale

# Все следующие команды необходимо выполнять из корня проекта.

# При необходимости переключаем репозитории в ветке develop.
# git checkout develop

# При необходимости определяем переменную окружения, отвечающую за тип создаваемого окружения.
# Про типы окружений будет рассказано подробнее.
# Значение по умолчанию: stage
# export TT_ENV=stage

# Обратите внимание на использование обёртки над docker-compose.
# Все операции необходимо выполнять через них.

# Собираем все контейнеры.
./bin/docker_compose_build_all.sh

####################################################
# Производим первоначальную настройку состояния игры
####################################################

# Создаём файл с кастомными настройками игры.
# Запомните его, он будет полезен в процессе разработки.
# В данном случае мы явно включаем в игре режим отладки.
# Файл settings_local.py добавлен в .gitignore и не сохраняется в репозиторий.
echo "DEBUG = True" > ./docker/the_tale/settings_local.py

# подготовливаем игру к запуску
./bin/before_first_start.sh

# В том числе команда создаём суперпользователя с параметрами по-умолчанию.
# ПОМЕНЯЙТЕ ИХ, если планируете давать доступ к игре другим людям.
# - ник: superuser
# - почта: superuser@example.com
# - пароль: 111111

Запуск игры

./bin/tt_game_start

# Теперь игра должна быть доступна по адресу "localhost".

# Остановить игру можно командой
# ./bin/tt_game_stop

# После остановки игры, можно остановить инфраструктуру
# ./bin/docker_compose.sh down

Типы окружений

Игра может запускаться в нескольких режимах, управляемых переменной окружения TT_ENV:

  • prod — окружение для запуска проекта в боевом режиме.

  • stage — окружение для запуска на тестовых серверах или на машине разработчика.

  • tests — окружение, оптимизированное для прогона тестов.

В большинстве случаев вам будет хватать stage.

Окружение test использует оптимизированную конфигурацию контейнеров для ускорения прогонки тестов:

  • PostgreSQL запускается на tmpfs то есть держит абсолютно все данные в памяти. Убедитесь, что у вас достаточно RAM.

Docker Compose

Вся конфигурация контейнеров находится в директории ./docker.

Базовую конфигурацию можно найти в файлах :

  • ./docker/docker-compose.build.yml — параметры сборки контейнеров.

  • ./docker/docker-compose.temlates.yml — общие параметры сервисов. В этот конфиги используется шаблонизация yaml.

  • ./docker/docker-compose.base.yml — персонализированные параметры сервисов, общие для всех окружений.

  • ./docker/docker-compose.$TT_ENV.yml — конфиги конкретных окружений.

Итоговое окружение получается с помощью переопределения нескольких конфигов. Это делается в обёртках над docker compose (см. ./bin/docker_compose.sh и прочие скрипты).

Сервисы разбиты на несколько профилей:

  • core — ключевые сервисы инфраструктуры: база, кэш, веб-сервер, etc.

  • services — все новые сервисы. От их доступности зависит работоспособность сайта.

  • workers — все старые сервисы. От их доступности зависят некоторая функциональность сайта. Например, регистрация.

  • site — сервис сайта.

  • utils — вспомогательные контейнеры для запуска утилит.

  • tasks-managers — сервис менеджера периодических задач (а-ля cron).

  • tasks — сервисы периодических задач, по сервису на задачу, управляются tasks manager-ом.

Сервисы без указанных профилей — сервисы инфраструктуры. В большинстве случаев все они должны быть запущены.

Опциональные репозитории

Часть проектов, родившихся в рамках разработки, доросли до стабильной версии и хостятся на pypi.org.

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

Репозитории:

Нюансы

Настройка форума проводится через админку Django.

Права пользователей также настраиваются через админку Django.

Админка Django доступна по адресу https://localhost/admin

После настройки, в базе игры не будет фраз для лингвистики, вместо них будут отображаться заглушки, описывающие тип фразы и её параметры. Фразы необходимо добавлять руками. Вы можете написать нам и мы вышлем дамп таблиц лингвистики для личного пользования.

В окружении разработчика используется самоподписанный сертификат, поэтому браузеры будут сообщать о «небезопасном соединении». Это нормально (для окружения разработчика). Если вы хотите избавиться от этого предупреждения, импортируйте сертификат к себе в систему или поправьте конфиги nginx.

Разработка

Процесс разработки с помощью Docker ещё не устоялся и может поменяться. На текущий момент:

  • Код из репозитория монтируется в соответствующие контейнеры.

  • Изменения в коде будут появляться в контейнерах, но запущенные сервисы не будут перезапускаться.

  • Если вы ведёте активную разработку одного из сервисов, рекомендуем запустить bash в соответствующем контейнере и запускать тесты и сервис вручную оттуда.

Во всех контейнерах, где необходимо, есть ряд утилит с именами tt_*. Они закрывают большинство нужд разработки.

Пример:

# обратите внимание на параметры
# --name — должен быть установлен в имя сервиса в docker-compose.base.yml, иначе другие сервисы не найдут его в сети.
# --entrypoint — указываем контейнеру запустить bash вместо команды по-умолчанию.
./bin/docker_compose.sh run utils-site bash

# запускаем какие-то команды

# стартуем сайт в обычном режиме
# tt_site -b 0.0.0.0:80 -w 4

# стартуем сайт в режиме разработчика
# tt_django runserver 0.0.0.0:80

# запускаем тесты
# tt_django test the_tale.portal

Запуск тестов

Тесты сервисов:

./bin/docker_compose.sh run tt-diary tt_run_tests

Главные тесты игры:

# Выключаем всё
./bin/tt_infrastructure_stop

# Запускаем только необходимые для тестов сервисы.
./bin/tt_infrastructure_start
./bin/docker_compose.sh --profile services up -d

./bin/docker_compose.sh run utils-site tt_django utils_run_tests

Предупреждение

Тесты игры идут очень долго. На моей машине около часа.

Небольшая часть тестов может сообщить об ошибках (обычно до 5) — это «нормально» — следствие большой вариативности логики игры. Стабилизация таких тестов — хорошая задача для нового разработчика.

Бэкапы

Контейнер utils-postgresql предоставляет экспериментальную функциональность по созданию бэкапов, загрузке их на amazon s3, выгрузке и восстановлению.