168 lines
8.4 KiB
Markdown
168 lines
8.4 KiB
Markdown
# 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. Скопируйте пример конфигурации:
|
||
|
||
```bash
|
||
cp docker/app.env.example docker/app.env
|
||
```
|
||
|
||
2. При необходимости отредактируйте `docker/app.env` (URL, пароли MySQL для локальной разработки).
|
||
|
||
### Запуск
|
||
|
||
```bash
|
||
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 видны без пересборки образа.
|
||
|
||
### Полезные команды
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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`). Рекомендуется шифрование:
|
||
|
||
```bash
|
||
ansible-vault encrypt group_vars/laravel/vault.yml
|
||
```
|
||
|
||
6. Сгенерируйте `vault_app_key` (например после локального `php artisan key:generate --show`).
|
||
|
||
### Запуск плейбука
|
||
|
||
Из каталога `ansible`:
|
||
|
||
```bash
|
||
ansible-playbook -i inventory/hosts.ini playbooks/site.yml --ask-vault-pass
|
||
```
|
||
|
||
Если vault не шифруется:
|
||
|
||
```bash
|
||
ansible-playbook -i inventory/hosts.ini playbooks/site.yml
|
||
```
|
||
|
||
### Пропуск получения сертификата (нет DNS / тест)
|
||
|
||
```bash
|
||
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 внутри контейнера.
|