Установка и запуск
Окружение игры организуется с помощью 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
git clone git@github.com:the-tale/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.
Если необходимо делать правки в них (например, добавить новую функциональность), их следует клонировать по аналогии с обязательными репозиториями и вручную поставить из исходников в нужные контейнеры.
Репозитории:
генератор имён персонажей: https://github.com/Tiendil/pynames
продвинутые перечисления: https://github.com/Tiendil/rels
генератор текста: https://github.com/Tiendil/utg
умные импорты для Python: https://github.com/Tiendil/smart-imports
генератор карты: https://github.com/the-tale/deworld
генератор заданий: https://github.com/the-tale/questgen
Нюансы
Настройка форума проводится через админку 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
, выгрузке и восстановлению.