Laravel + Docker + Ansible (thin repo)

Воспроизводимая инфраструктура: локально — Docker Compose; на сервере Debian 11 — Ansible (Docker, TLS, GitLab Runner); CI/CD — GitLab с self-hosted runner.

Структура репозитория

Путь	Назначение
Корень	Исходный код Laravel
docker/	Образ PHP-FPM, Nginx, файл app.env (не секреты в примере)
docker-compose.yml, docker-compose.prod.yml	Сервисы приложения
ansible/	Плейбуки, роли, переменные
.gitlab-ci.yml	Pipeline деплоя при пуше в основную ветку

Секреты для Ansible храните в ansible/group_vars/laravel/vault.yml (рекомендуется ansible-vault). Пример без шифрования — vault.yml.example.

Конфигурация приложения в Docker задаётся файлами (docker/app.env), а не переменными окружения хоста. Для GitLab CI целевой сервер и путь к проекту задаются переменными в интерфейсе GitLab (см. ниже) — это не конфигурация приложения.

---

Часть 1. Локальный запуск

Требования

• Docker и Docker Compose v2

Подготовка

1. Скопируйте пример конфигурации:

   cp docker/app.env.example docker/app.env
   

2. При необходимости отредактируйте docker/app.env (URL, пароли MySQL для локальной разработки).

Запуск

docker compose up -d --build

• Приложение: http://localhost:8080 (порт меняется через HTTP_PORT в docker-compose.yml, по умолчанию 8080).
• phpMyAdmin: http://localhost:8080/pma/ — вход пользователем БД db и паролем из docker/app.env (MYSQL_PASSWORD).

Первый запуск PHP-контейнера выполнит composer install (зависимости в именованном томе laravel_vendor), сгенерирует APP_KEY при необходимости и применит миграции. Код монтируется с хоста — правки PHP/Blade видны без пересборки образа.

Полезные команды

docker compose logs -f php
docker compose exec php php artisan migrate:status

---

Часть 2. GitLab CI/CD

Self-hosted Runner

Runner ставится Ansible-ролью gitlab_runner (Docker executor, тег docker, доступ к docker.sock).

Регистрация использует токен из Ansible Vault (vault_gitlab_runner_token).

Pipeline

Файл .gitlab-ci.yml: при пуше в основную ветку (CI_DEFAULT_BRANCH) job deploy_production подключается по SSH к серверу и выполняет git fetch / git reset --hard и docker compose ... up -d --build.

Переменные в GitLab (Settings → CI/CD → Variables)

Переменная	Маскировать	Описание
CI_DEPLOY_SSH_PRIVATE_KEY	да	Приватный ключ для пользователя деплоя на сервере
DEPLOY_HOST	нет	Хост или IP сервера
DEPLOY_USER	нет	Обычно deploy
DEPLOY_PATH	нет	Каталог клона репозитория на сервере (как в Ansible project_path)

На сервере в authorized_keys пользователя деплоя должен быть публичный ключ, соответствующий этому приватному ключу. Удобно добавить его в Ansible в deploy_authorized_keys в ansible/group_vars/laravel/main.yml.

Доступ Git на сервере

Для приватного репозитория на сервере нужен доступ к GitLab (Deploy Key или vault_git_repo_url с токеном при первом клоне). После клона можно переключить origin на SSH и использовать deploy key.

---

Часть 3. Ansible (Debian 11)

Подготовка

1. Установите Ansible на управляющей машине (например pip install ansible или пакет дистрибутива).

2. Скопируйте инвентарь и vault:

   cd ansible
   cp inventory/hosts.ini.example inventory/hosts.ini
   cp group_vars/laravel/vault.yml.example group_vars/laravel/vault.yml
   

3. В inventory/hosts.ini укажите ansible_host и пользователя SSH (часто root для первого захода).

4. В group_vars/laravel/main.yml задайте:

   • project_domain — домен для Let's Encrypt и APP_URL;
   • letsencrypt_email — почта для ACME;
   • git_repo_url_public — URL публичного репозитория или оставьте пустым и задайте приватный URL в vault;
   • deploy_authorized_keys — список SSH-публичных ключей для пользователя deploy.

5. Заполните group_vars/laravel/vault.yml (минимум токен регистрации Runner и пароли БД, см. комментарии в vault.yml.example). Рекомендуется шифрование:

   ansible-vault encrypt group_vars/laravel/vault.yml
   

6. Сгенерируйте vault_app_key (например после локального php artisan key:generate --show).

Запуск плейбука

Из каталога ansible:

ansible-playbook -i inventory/hosts.ini playbooks/site.yml --ask-vault-pass

Если vault не шифруется:

ansible-playbook -i inventory/hosts.ini playbooks/site.yml

Пропуск получения сертификата (нет DNS / тест)

ansible-playbook -i inventory/hosts.ini playbooks/site.yml --ask-vault-pass --skip-tags letsencrypt

Тег letsencrypt назначен задаче certbot в роли nginx_letsencrypt.

Что делает плейбук

1. common — пользователь deploy, каталог проекта, authorized_keys.
2. docker — пакеты docker.io и docker-compose-plugin, группа docker.
3. security — UFW: 22, 80, 443.
4. laravel_docker — клон репозитория, шаблон docker/app.env, docker compose up (с docker-compose.prod.yml: Nginx приложения только на 127.0.0.1:8080).
5. nginx_letsencrypt — системный Nginx как reverse proxy на 127.0.0.1:8080, Certbot (Let's Encrypt), попытка включить certbot.timer (при отсутствии — обычно остаётся cron из пакета).
6. gitlab_runner — установка и однократная регистрация runner с тегом docker.

После успешного выполнения приложение доступно по HTTPS на project_domain, phpMyAdmin — по https://<домен>/pma/.

---

Переменные: краткая таблица

Где	Что задать
docker/app.env (локально, из примера)	Параметры Laravel и MySQL для Compose
ansible/group_vars/laravel/main.yml	Домен, email LE, URL репозитория, ключи SSH
ansible/group_vars/laravel/vault.yml	Токен Runner, пароли MySQL, APP_KEY, опционально URL приватного Git
GitLab CI Variables	SSH-ключ, DEPLOY_HOST, DEPLOY_USER, DEPLOY_PATH

---

Технические детали

• Очереди: по умолчанию QUEUE_CONNECTION=redis, воркер — сервис queue в Compose.
• Миграции: выполняются entrypoint-скриптом PHP-контейнера при старте.
• Тонкий репозиторий: vendor не в Git — в Docker том laravel_vendor и установка через Composer внутри контейнера.