tabun/CONTRIBUTING.md

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

Для запуска проекта нужен Docker >=18.06.0 с docker-compose >=1.22.0. Для использования скрипта сборки и запуска вместо устаревшего docker-compose требуется CLI-плагин Compose (доступен для Docker >=18.09.0).

Для сборки продакшен сервера используется docker-compose.yml, для разработки — docker-compose.develop.yml. Отличия сборки для разработки:

• все порты открываются на определённом IP-адресе, по умолчанию 127.0.0.1, настраивается переменной окружения HOST_IP в файле .env;
• все изменения в папках frontend (ассеты) и templates/skin/synio/locale/ru_RU/LC_MESSAGES/parts (языковые файлы формата GetText) отслеживаются и будут вызывать пересборку упакованных ассетов и применение их на сервере — не требуется перезапускать контейнеры;
• создаётся отдельный контейнер для фронтенда, в котором крутится отслеживание упомянутых выше изменений;
• возможна отладка PHP-кода посредством xDebug;
• для управления базой данных доступен phpMyAdmin в стандартной поставке с автоматической авторизацией;
• при использовании скрипта сборки и запуска дополнительно происходит копирование папки /vendor из контейнера бекенда в основную среду разработки для корректной работы систем IntelliSense в IDE.

Если компьтер, на котором ведётся разработка, и компьютер, на котором запускается проект, — разные, то в файле .env в корне проекта необходимо указать IP-адрес в локальной сети компьютера-сервера. Пример оформления файла:

HOST_IP=10.0.1.1

tl;dr

Подготовка dev-сборки к работе:

~/project_directory$ echo "HOST_IP=<IP_ADDRESS_OF_PROJECT_SERVER>" > .env && ./run.sh dev - rebuild

Дальнейший запуск сборки:

~/project_directory$ ./run.sh dev

Запуск скриптом

Сборка и запуск осуществляются с помощью run.sh в корневой папке проекта. Формат вызова:

run.sh [dev|- [<custom_name>|- [rebuild|- [log|-]]]]

Порядок аргументов важен. Для пропуска аргумента используйте дефис. Расшифровка:

• dev соберёт и запустит Табун для разработки.
• С помощью <custom_name> можно задать другое имя проекта (и результирующих контейнеров). По умолчанию tabun, для dev-сборки — tabun-dev.
• rebuild вызовет принудительную пересборку (с использованием кеширования, см. ниже как нивелировать) и не запустит контейнеры. Если совмещён с dev, то в проекте появится или пересоздастся папка vendor с библиотеками, подтянутыми композером, изменения в ней не влияют на сервер.
• log выведет подробный лог в файл build.log в корневой папке проекта (в .gitignore отсутствует, поэтому удаляйте этот файл, чтобы он не попал в репозиторий).

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

Запуск вручную

Сборку и запуск можно произвести вручную командой docker-compose -f docker-compose.yml up. Для оптимизации процесса и собранных образов контейнеров рекомендуется активировать BuildKit, который используется по умолчанию с Docker 23.0:

• либо с помощью docker compose (без дефиса) в Docker >=18.09.0 с CLI-плагином compose-cli-plugin,
• либо с указанием переменных окружения COMPOSE_DOCKER_CLI_BUILD=1 DOCKER_BUILDKIT=1 при вызове docker-compose (для версий Docker < 23.0).

Как подготовить окружение к чистой пересборке сервера?

run.sh - - rebuild пересобирает контейнеры и частично образы, если в Dockerfile были внесены изменения (спойлер: не всегда). Если же требуется полная пересборка, можно воспользоваться следующими командами:

• docker builder prune -a (чистит кеш сборки, не влияет на собранные образы и контейнеры)
• docker container rm <проект-сервис-индекс> [<проект-сервис-индекс>...] (удаляет отдельно взятый(-е) контейнер(-ы) с названием(-ями) проект-сервис-индекс; docker container ls -a для вывода списка всех контейнеров)
  или docker container prune (удаляет все контейнеры, когда-либо созданные на хосте (не только Табунские!))
• docker volume rm <название> [<название>...] (удаляет отдельно взятое(-ые) хранилище(-а), не привязанное(-ые) ни к одному контейнеру; docker volume ls для вывода списка всех хранилищ)
  или docker volume prune (удаляет все тома, не привязанные ни к одному контейнеру (не только Табунские!))
• docker image rm <название> [<название>...] (удаляет отдельно взятый(-ые) образы(-ы), не привязанный(-ые) ни к одному контейнеру; docker image ls для вывода списка всех образов (-a для показа вообще всех))
  или docker image prune (удаляет ненужные образы; с аргументом -a удалит так же все образы, не привязанные ни к одному контейнеру (не только Табунские!))

Если производятся изменения в скриптах сборки, влияющие на стартовое содержимое хранилищ, их (хранилища) нужно предварительно удалить.

Работа с проектом

После запуска (в случае dev-сборки — на 127.0.0.1 или заданном адресе) будут открыты порты:

• 8000 — собственно, сам Табун;
• 8080 — интерфейс phpMyAdmin (авторизация не требуется). Доступен только на dev-сборке;
• 1080 — интерфейс отладочного почтового сервера, позволяющего тестировать связанный с отправкой писем функционал без действительной отправки. Доступен только на dev-сборке;
• 9003 — xDebug. При использовании DBGp Proxy Tool IDE-ключ — tabun. Доступен только на dev-сборке.
• 3307 — БД. Доступен только на dev-сборке.

База данных инициализируется автоматически при старте её контейнера и наполняется небольшой порцией тестовых данных (несколько аккаунтов, блогов, записей в них, комментариев). Для этого используются sql-файлы из папки fixtures — в migrations/ находится схема БД и в data/ тестовое наполнение.

Преднастроенные аккаунты на сайте для тестирования (логин:пароль):

• Celestia:celestia
• Luna:constellations
• Sparkle:scrolls
• Spitfire:feathers

При изменении существующей структуры БД на dev-сборке помимо создания дополнительных файлов миграции необходимо проверять соответствие тестового наполнения внесённым изменениям. Иными словами, после добавления файла миграции, изменяющего структуру БД, нужно заглянуть во все файлы в папке data/ и проверить SQL-запросы в них. Например, при добавлении новых столбцов нужно внести значения для них в соответствующих INSERT-запросах в 0001_example.sql, т.к. в них не прописан список заполняемых столбцов и при попытке выполнить такой запрос в таблице с изменённым набором столбцов БД упадёт (как ни странно).

Прочие сервисы

Redis

Порт 6379 (внутренний, не открывается за пределы docker)

Базы:

• 1 — брокер Celery
• 2 — результаты задач
• 3 — сессии PHP
• 4 — кеш приложения

php-fpm

Порт 9000 (внутренний, не открывается за пределы docker)

База данных

(этот раздел устарел)

Для загрузки SQL-дампов либо выполнения любых других корректных комманд, в т.ч. сжатые (*.sql.gz) существует комманда _load_fixture

При использовании команды требуется остановить проект, если он запущен с помощь vagga run. Если процессы запущены по отдельности, например, vagga run --only php, vagga run --only mysql и т.д., то нужно остановить только процесс mysql

Например, загрузка сжатого дампа будет выглядеть примерно так:

vagga _load_fixture my/test/dump.sql.gz

Либо, применение патча:

vagga _load_fixture my/patches/31337_info.sql

ElasticSearch

docker-compose exec <app> php /app/engine/console/ls.php reindex topics
docker-compose exec <app> php /app/engine/console/ls.php reindex comments

(<app> заменить на имя контейнера с бекендом)