docker-compose/AGENTS.md

# Repository Guidelines

## Project Structure & Module Organization

This is a multi-service Docker Compose infrastructure project organized as follows:

- **Root**: `compose.yaml` (orchestrates all services), `arty.yml` (centralized configuration)
- **Service Directories**: Each service has its own folder (`core/`, `sexy/`, `proxy/`, `ai/`, etc.) containing:
  - `compose.yaml`: Service-specific Docker Compose configuration
  - Service-specific configuration files and initialization scripts
- **Shared Infrastructure**: `core/` provides PostgreSQL 16 and Redis 7 for all services
- **Proxy**: `proxy/` contains Traefik reverse proxy with dynamic security configurations in `proxy/dynamic/`

All services connect to a single external Docker network (`falcon_network`) defined by `$NETWORK_NAME`.

## Build, Test, and Development Commands

All commands use `pnpm arty` (leveraging scripts defined in `arty.yml`):

- `pnpm arty up` - Start all services in detached mode
- `pnpm arty down` - Stop and remove all containers
- `pnpm arty ps` - List running containers
- `pnpm arty logs` - Follow logs for all services
- `pnpm arty restart` - Restart all services
- `pnpm arty pull` - Pull latest images for all services
- `pnpm arty config` - View rendered configuration with variables substituted
- `pnpm arty net/create` - Create the external Docker network (required before first run)

## Coding Style & Naming Conventions

**Environment Variables:**
- Pattern: `{SERVICE}_COMPOSE_PROJECT_NAME`, `{SERVICE}_TRAEFIK_HOST`, `{SERVICE}_DOCKER_IMAGE`
- Defined in `arty.yml` under `envs.default` with sensible defaults
- Sensitive values stored in `.env` (passwords, secrets, API keys)

**Service Configuration:**
- Use `${VARIABLE:-default_value}` syntax for environment variable references
- Container names: `${SERVICE_COMPOSE_PROJECT_NAME}_app` or `${SERVICE_COMPOSE_PROJECT_NAME}_component`
- Volume names: `${SERVICE_COMPOSE_PROJECT_NAME}_volume_name`

**Traefik Labels:**
- HTTP → HTTPS redirect on `web` entrypoint (port 80)
- SSL termination on `web-secure` entrypoint (port 443)
- All routers scoped to `${NETWORK_NAME}` network
- Use middleware pattern: `${SERVICE_COMPOSE_PROJECT_NAME}-middleware-name`

**File Organization:**
- Database initialization scripts: `core/postgres/init/*.sh`
- Dynamic Traefik configuration: `proxy/dynamic/*.yaml`
- Service data exports: `{service}/` (e.g., `sexy/directus.yaml`)

## Testing Guidelines

This is an infrastructure project with no automated test suite. Validation is done through:

**Service Health Checks:**
- Most services include healthcheck definitions in their `compose.yaml`
- Check service health: `docker ps` (look for "healthy" status)
- Inspect specific service: `docker inspect <container_name>`

**Manual Verification:**
- Access services via configured hostnames (e.g., `https://sexy.pivoine.art`)
- Check Traefik dashboard: `https://proxy.pivoine.art` (requires HTTP Basic Auth)
- Test SSL certificates: `curl -I https://<service>.pivoine.art`
- Monitor logs: `pnpm arty logs` or `docker logs <container_name>`

**Troubleshooting:**
- Database connectivity: `docker exec core_postgres psql -U $DB_USER -l`
- Network exists: `docker network ls | grep falcon`
- Check configuration rendering: `pnpm arty config`

## Commit & Pull Request Guidelines

**Commit Message Format:**
- Follow conventional commits: `type: description`
- Types: `feat`, `fix`, `docs`, `refactor`, `chore`
- Keep description concise and imperative mood
- Add detailed explanation in commit body when needed
- Include co-author attribution: `Co-Authored-By: Claude <noreply@anthropic.com>`
- Add generation marker: `🤖 Generated with [Claude Code](https://claude.com/claude-code)`

**Examples:**
```
feat: add sexy/bundle/update script to refresh Directus extensions

Added arty script to update Directus extension bundle from the latest
sexy_frontend image. This ensures the API container always has the
latest extensions when the frontend image is rebuilt.
```

```
fix: enable email functionality in Linkwarden with correct SMTP configuration

- Add NEXT_PUBLIC_EMAIL_PROVIDER=true to enable email features
- Change EMAIL_SERVER protocol from smtp:// to smtps:// for port 465
```

**Changes to Make:**
- Update `arty.yml` for new environment variables or scripts
- Update service `compose.yaml` files for container configuration
- Add initialization scripts to `core/postgres/init/` for new databases
- Document new services in README.md
- Never commit secrets - they belong in `.env` only

## Security & Configuration Tips

**Secrets Management:**
- Store all secrets in `.env` (never committed to git)
- Use Apache htpasswd format for HTTP Basic Auth: `openssl passwd -apr1 'password'`
- Escape `$` signs with `$$` in `.env` files for Docker Compose compatibility

**Security Headers:**
- Global security settings: `proxy/dynamic/security.yaml`
- Automatically reloaded by Traefik (no restart needed)
- Includes HSTS, X-Frame-Options, CSP, and rate limiting

**Database Access:**
- PostgreSQL exposed on port 5432 for local development
- All databases use shared credentials: `$DB_USER` and `$DB_PASSWORD`
- Database initialization: `core/postgres/init/01-init-databases.sh`

**SSL Certificates:**
- Automatic Let's Encrypt via Traefik ACME
- Requires `ADMIN_EMAIL` in `.env`
- Certificates stored in `proxy_letsencrypt_data` volume

**Network Architecture:**
- All services must connect to external network: `${NETWORK_NAME}`
- Create network before first run: `pnpm arty net/create`
- Network must be external and created separately from compose stacks