# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this repo is

Coolify stack definitions for LAIL — a French cooperative cloud infrastructure. Stacks are Docker Compose files deployed via Coolify (no local build/run tooling exists; deployment is done through the Coolify UI against the remote host).

## Repository structure

```
stacks/
├── lail-apps/          # Shared LAIL applications (one instance per service)
├── lail-infra/         # Infrastructure services (Authentik SSO, SFTPGo)
├── lail-sites/         # Website deployments
└── structures/         # Multi-tenant per-organization Nextcloud instances
    └── _templates/     # Copy and replace XXXXXX placeholders for new orgs
```

## Docker Compose patterns used across stacks

**Environment variables** — Coolify injects these automatically; reference them in compose files as-is:
- `SERVICE_URL_<NAME>` — public URL for the service
- `SERVICE_USER_<NAME>` / `SERVICE_PASSWORD_<NAME>` — generated credentials
- `SERVICE_PASSWORD_64_<NAME>` — 64-char password (used for Redis, long secrets)
- `SERVICE_HEX_32_<NAME>` — 32-char hex value (used for encryption keys/secrets)

**Data paths** — all persistent data lives on the host at:
- `/data/lail-apps/<app-name>/` — shared apps
- `/data/lail-structures/<org-name>/` — per-organization data

**Database readiness** — always use `depends_on` with `condition: service_healthy` and define `healthcheck` on the DB service (`pg_isready` for Postgres, `redis-cli ping` for Redis).

**Database version** — PostgreSQL 16-alpine is the standard.

## SSO/OIDC

Central identity provider is Authentik at `sso.lail.cloud`. When adding SSO to a new service, use its OIDC endpoints. Each app's README.md contains notes on SSO configuration status and any app-specific quirks.

## Adding a new structure (multi-tenant org)

1. Copy `stacks/structures/_templates/` into `stacks/structures/<org-name>/`
2. Replace every occurrence of `XXXXXX` with the org name
3. Update data paths: `/data/lail-structures/XXXXXX/` → `/data/lail-structures/<org-name>/`

## Special requirements

**Collabora** requires Docker host-level capabilities: `cap_add: [SYS_ADMIN]`, device `/dev/fuse`, and AppArmor profile `unconfined`. This cannot run in a constrained Docker environment.

**Paheko** embeds its PHP config (`config.local.php`) as an inline file written via `docker-compose.yaml` — edits to PHP config go in the compose file itself, not a separate file.

**N8N** uses a queue-mode architecture: separate `worker` and `task-runner` services alongside the main service, all sharing a Redis queue and Postgres DB.