docker-stack-octane-swoole

Files (6)

• SKILL.md
• octane-safety-checklist.md · rules/
• Dockerfile.octane · templates/
• docker-compose.yml · templates/
• nginx-default.conf · templates/
• octane-entrypoint.sh · templates/

SKILL.md (first lines)

# Docker Stack Octane (Swoole)

## Consistency First

A stack canônica deste perfil roda Octane com Swoole na porta interna `8000`, atrás de Nginx que faz `proxy_pass`. Use apenas em projetos **novos**; para migrar um projeto FPM existente, vá em `enable-octane-swoole`.

Base image canônica: `phpswoole/swoole:php8.4` (vem com `ext-swoole` compilado). **Não** rodar `pecl install swoole` em cima — duplica a extensão e o worker recusa boot. Libs de SO, Node 22 e extensões PHP comuns ficam em `_shared/docker-base-deps.md`; sempre que mudar versão de Node ou Chromium libs, edite o shared e propague.

Se já existe `docker-compose.yml` customizado (sem o header desta skill e sem marcador do Sail), pare e peça confirmação antes de sobrescrever.

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: `phpswoole/swoole:php8.4`.
- Comando do `app`: `php artisan octane:start --server=swoole --host=0.0.0.0 --port=8000`.
- Hot reload em dev: variável `OCTANE_WATCH=true` lida pelo entrypoint condicional; adiciona `--watch` ao comando.
- Services obrigatórios: `app`, `queue`, `reverb`, `vite`, `nginx`, `postgres`, `redis`, `mailpit`.
- Services opcionais (profiles desligados por padrão): `minio`, `ollama`, `qdrant`.
- Mesma imagem em `app`/`queue`/`reverb`/`vite` com comandos diferentes; sem Supervisor.
- 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 vars Octane: `OCTANE_SERVER=swoole`, `OCTANE_HTTPS=true`, `OCTANE_MAX_REQUESTS=500`, `OCTANE_WATCH=false` (dev pode ligar).
- `.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`.
- 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 variáveis (recebidas por `init-project` ou perguntar): `LOCALE_FULL` (`pt_BR.UTF-8` por padrão), `PROJECT_NAME` (basename do diretório).

- [ ] 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-octane-swoole" "$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). Migre via enable-octane-swoole.\n' "${CUSTOM_COMPOSE_FILES[*]}"
    exit 1
  elif [[ -f docker-compose.yml ]] && grep -q "generated by docker-stack-octane-swoole" docker-compose.yml; then
    echo "docker-compose.yml canônico Octane 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 Octane 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 Octane."; exit 1; }
    fi
  else
    printf 'Compose existente detectado (%s). Migre via enable-octane-swoole.\n' "${EXISTING_COMPOSE_FILES[*]}"
    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 templates:

```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-octane-swoole/templates/Dockerfile.octane > docker/php/Dockerfile
sed "s/{{PROJECT_NAME}}/$PROJECT_NAME/g" .agents/skills/docker-stack-octane-swoole/templates/docker-compose.yml > docker-compose.yml
cp .agents/skills/docker-stack-octane-swoole/templates/nginx-default.conf docker/nginx/default.conf
cp .agents/skills/docker-stack-octane-swoole/templates/octane-entrypoint.sh docker/php/entrypoint.sh
chmod +x docker/php/entrypoint.sh
```

O `entrypoint.sh` inspeciona `OCTANE_WATCH`: quando `true`, adiciona `--watch`; caso contrário, sobe sem watcher (produção).

- [ ] 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" \
           "OCTANE_SERVER=swoole" "OCTANE_HTTPS=true" \
           "OCTANE_MAX_REQUESTS=500" "OCTANE_WATCH=false"; 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"
  fi
}

From CoringaWc/ai-first-kit, MIT.

More from CoringaWc/ai-first-kit