docker-stack-fpm

Files (6)

• SKILL.md
• shared-services.md · rules/
• Dockerfile.fpm · templates/
• docker-compose.yml · templates/
• fpm-entrypoint.sh · templates/
• nginx-default.conf · templates/

SKILL.md (first lines)

# Docker Stack FPM

## Consistency First

A stack canônica deste projeto roda PHP 8.4 FPM com Nginx em containers separados. Não rode Octane, Roadrunner ou `php artisan serve` neste perfil. O Dockerfile e o `docker-compose.yml` ficam em `docker/php/`, `docker/nginx/` e na raiz; nunca dispersados.

Se já existe `docker-compose.yml` customizado (qualquer compose sem o header de geração desta skill e sem marcadores do Sail), pare e peça confirmação antes de sobrescrever. Compose padrão do Sail pode ser arquivado e substituído pelo canônico do kit.

A imagem `app` carrega libs do Chromium do SO porque Pest Browser roda dentro do próprio container. Não use a imagem oficial do Playwright como base; ela não traz PHP.

O entrypoint da stack instala dependências ausentes em ambiente local quando `AUTO_INSTALL_DEPS=true`: `composer install` quando `vendor/autoload.php` está ausente e `npm install` quando `node_modules/.install-complete` está ausente. Em produção/CI, use `AUTO_INSTALL_DEPS=false` para falhar cedo se as dependências não estiverem pré-instaladas. Se `composer.json` usa o repositório privado do Filament, `auth.json`, `COMPOSER_AUTH` ou auth global do Composer precisa estar disponível antes do Composer.

## Quick Reference

- Para qualquer alteração em `/vite`, `/ws`, `/app`, HMR, Reverb ou Nginx, aplicar antes `vite-reverb-nginx-routing`.
- Base: `php:8.4-fpm-bookworm`.
- Extensões PHP: `pdo_pgsql`, `bcmath`, `gd`, `intl`, `mbstring`, `opcache`, `pcntl`, `redis`, `zip`, `pgsql`.
- Pacotes Chromium para Playwright: `libnss3`, `libatk1.0-0`, `libatk-bridge2.0-0`, `libcups2`, `libdbus-1-3`, `libdrm2`, `libxkbcommon0`, `libxcomposite1`, `libxdamage1`, `libxfixes3`, `libxrandr2`, `libgbm1`, `libasound2`, `libpangocairo-1.0-0`, `libpango-1.0-0`, `libcairo2`, `fonts-liberation`.
- Node: instalar via NodeSource pinado em Node 22 (LTS atual).
- Services: `app`, `queue`, `reverb`, `vite`, `nginx`, `postgres`, `redis`, `mailpit` (sempre); `minio`, `ollama`, `qdrant` (profiles desligados por padrão).
- Sem Supervisor dentro do `app`; `queue`, `reverb` e `vite` têm services próprios com a mesma imagem.
- Nginx expõe Vite apenas em `/vite/` e Reverb apenas em `/ws/`; não publique a porta `5173` para o browser, bloqueie `/ws/apps/` publicamente e não reserve `/app` para WebSocket.
- Portas de banco, Redis, Mailpit e serviços opcionais devem bindar em `127.0.0.1` por padrão.
- `.env` canônico: `DB_HOST=postgres`, `APP_SERVICE=app`, `WWWUSER=1000`, `WWWGROUP=1000`.
- Build antes do Laravel/Sail existir: `docker compose build app`.
- Build depois do Sail existir: `vendor/bin/sail build --no-cache`.
- Subir tudo depois do Sail existir: `vendor/bin/sail up -d`.
- Antes de handoff, aplique `verify-before-commit` e siga `verify-before-commit/rules/verify-gate.md`: `vendor/bin/sail composer verify` é o gate obrigatório.

## Workflow

- [ ] Detectar `LOCALE_FULL` (`pt_BR.UTF-8` por padrão) e `PROJECT_NAME` (basename do diretório atual). Quando chamado por outra skill, receber por env var.

- [ ] Arquivar compose padrão do Sail antes de gerar a stack do kit:

```bash
COMPOSE_FILES=(compose.yaml compose.yml docker-compose.yml docker-compose.yaml)
EXISTING_COMPOSE_FILES=()
CANONICAL_COMPOSE=false
CUSTOM_COMPOSE_FILES=()

for COMPOSE_FILE in "${COMPOSE_FILES[@]}"; do
  [[ -f "$COMPOSE_FILE" ]] && EXISTING_COMPOSE_FILES+=("$COMPOSE_FILE")
done

for COMPOSE_FILE in "${EXISTING_COMPOSE_FILES[@]}"; do
  if [[ "$COMPOSE_FILE" == "docker-compose.yml" ]] && grep -q "generated by docker-stack-fpm" "$COMPOSE_FILE"; then
    continue
  fi
  grep -Eq "laravel\.test|vendor/laravel/sail" "$COMPOSE_FILE" || CUSTOM_COMPOSE_FILES+=("$COMPOSE_FILE")
done

if ((${#EXISTING_COMPOSE_FILES[@]} > 0)); then
  if ((${#CUSTOM_COMPOSE_FILES[@]} > 0)); then
    printf 'Compose customizado detectado (%s). Sobrescrever? [y/N] ' "${CUSTOM_COMPOSE_FILES[*]}"
    read -r ANSWER
    [[ "$ANSWER" =~ ^[Yy]$ ]] || { echo "Abortando geração da stack FPM."; exit 1; }
  elif [[ -f docker-compose.yml ]] && grep -q "generated by docker-stack-fpm" docker-compose.yml; then
    echo "docker-compose.yml canônico da stack FPM detectado; reexecutando idempotente."
    CANONICAL_COMPOSE=true
  elif grep -Eq "laravel\.test|vendor/laravel/sail" "${EXISTING_COMPOSE_FILES[@]}"; then
    if [[ "${ALLOW_SAIL_COMPOSE_REPLACE:-0}" == "1" ]]; then
      echo "Compose padrão do Sail detectado; substituindo pela stack FPM do kit."
    else
      printf 'Compose com marcadores Sail detectado (%s). Sobrescrever? [y/N] ' "${EXISTING_COMPOSE_FILES[*]}"
      read -r ANSWER
      [[ "$ANSWER" =~ ^[Yy]$ ]] || { echo "Abortando geração da stack FPM."; exit 1; }
    fi
  else
    printf 'Compose existente detectado (%s). Sobrescrever? [y/N] ' "${EXISTING_COMPOSE_FILES[*]}"
    read -r ANSWER
    [[ "$ANSWER" =~ ^[Yy]$ ]] || { echo "Abortando geração da stack FPM."; exit 1; }
  fi

  TS="$(date +%Y%m%d%H%M%S)"
  for COMPOSE_FILE in "${EXISTING_COMPOSE_FILES[@]}"; do
    [[ "$CANONICAL_COMPOSE" == "true" && "$COMPOSE_FILE" == "docker-compose.yml" ]] && continue
    mv "$COMPOSE_FILE" "${COMPOSE_FILE}.bak.${TS}"
  done
fi
```

- [ ] Renderizar Dockerfile e entrypoint com `LOCALE_FULL`:

```bash
mkdir -p docker/php docker/nginx
LOCALE_FULL="${LOCALE_FULL:-${LOCALE:-pt_BR.UTF-8}}"
sed "s/{{LOCALE}}/$LOCALE_FULL/g" .agents/skills/docker-stack-fpm/templates/Dockerfile.fpm > docker/php/Dockerfile
cp .agents/skills/docker-stack-fpm/templates/fpm-entrypoint.sh docker/php/entrypoint.sh
chmod +x docker/php/entrypoint.sh
```

- [ ] Renderizar `docker-compose.yml` com `PROJECT_NAME`:

```bash
sed "s/{{PROJECT_NAME}}/$PROJECT_NAME/g" .agents/skills/docker-stack-fpm/templates/docker-compose.yml > docker-compose.yml
cp .agents/skills/docker-stack-fpm/templates/nginx-default.conf docker/nginx/default.conf
```

- [ ] Normalizar `.env` e `.env.example` (idempotente):

```bash
for KEY in "APP_SERVICE=app" "WWWUSER=1000" "WWWGROUP=1000" "FORWARD_DB_PORT=5432" "FORWARD_REDIS_PORT=6379"; do
  KEY_NAME="${KEY%%=*}"
  for ENV_FILE in .env .env.example; do
    [[ -f "$ENV_FILE" ]] || continue
    grep -q "^${KEY_NAME}=" "$ENV_FILE" || echo "$KEY" >> "$ENV_FILE"
  done
done

set_env_entry() {
  local ENV_FILE="$1" ENTRY="$2" MODE="${3:-force}" KEY_NAME="${ENTRY%%=*}"
  [[ "$MODE" == keep && $(grep -c "^${KEY_NAME}=" "$ENV_FILE") -gt 0 ]] && return 0
  if grep -q "^${KEY_NAME}=" "$ENV_FILE"; then
    sed -i "s|^${KEY_NAME}=.*|${ENTRY}|" "$ENV_FILE"
  elif grep -q "^# ${KEY_NAME}=" "$ENV_FILE"; then
    sed -i "s|^# ${KEY_NAME}=.*|${ENTRY}|" "$ENV_FILE"
  else
    echo "$ENTRY" >> "$ENV_FILE"

From CoringaWc/ai-first-kit, MIT.

More from CoringaWc/ai-first-kit