# Compose & Infrastructure Conventions

This document outlines the standard conventions and best practices for Docker
and Podman Compose files, volume layouts, networking, and smart image packaging
across our infrastructure.

---

## 1. Storage & Host Volume Conventions

- **Root Project Directory:** All project state lives under
  `/volume1/docker/<stack-name>/` (e.g., `/volume1/docker/auth-yes/`,
  `/volume1/docker/spire/`).
- **Standard Folder Naming:** Always use **`data`** for persistent application
  and database storage (never `db` or fragmented subfolders when a single root
  directory suffices).
- **Local Bind Mount Syntax:** Always use the standard `driver_opts` local bind
  definition:
  ```yaml
  volumes:
    <service>-data:
      driver: local
      driver_opts:
        type: none
        device: ${<STACK>_DATA_PATH}
        o: bind
  ```
- **Zero-Trust Inter-Process Sockets:**
  - Sockets shared across stacks (e.g., the SPIFFE Workload API `agent.sock`)
    MUST use a **named volume** (`spire-socket`).
  - Application containers mount this volume read-only (`:ro`), ensuring zero
    access to sensitive server CA keys, SQLite databases, or internal host
    state.
  - Client stacks declare `spire-socket` as `external: true`.

---

## 2. Smart Container Images & Scripting Guidelines

- **Pragmatic Scripting in Compose:**
  - Short one-line commands, flags, or glue checks in `command:` or
    `entrypoint:` are fine.
  - Complex configuration generation, heredoc templating (`cat << 'EOF'`), and
    heavy lifecycle bootstrapping MUST NOT be embedded in Compose files.
- **Smart Image Packaging & Repository Segregation:**
  - Self-seeding configuration and container lifecycle scripts belong in the
    container image.
  - All smart image logic, Dockerfiles, entrypoint scripts (`entrypoint.sh`),
    and configuration templates (`templates/`) must be cleanly segregated in
    dedicated directories in the codebase (e.g., `spire/`).
- **Persistence & User Modification:**
  - Smart image entrypoints must follow the self-seeding pattern: check if the
    target configuration exists on the host mount.
  - If missing on first boot $\rightarrow$ atomically write the master template
    with guiding comments.
  - If already present $\rightarrow$ leave it untouched, preserving all user
    modifications across restarts and image updates.

---

## 3. Environment Variables & Clean YAML

- **No Inline Variable Fallbacks in Compose:**
  - Always write clean variable references: `${REG}`, `${GHCR_REG}`,
    `${SYSTEM_DOMAIN}`, `${SPIRE_DATA_PATH}`.
  - Do NOT use inline defaults (e.g., `${REG:-quay.atyg.org}`) inside the
    Compose file.
  - All default values belong strictly in `.env` or the interactive setup wizard
    (`infra/setup.ts`).
- **Parameterize Registry Endpoints:**
  - Always prefix images with `${REG}/library/<image>:<tag>` or
    `${GHCR_REG}/<org>/<image>:<tag>`.

---

## 4. Networking & Traefik Routing

- **Ingress Network:**
  - Web-facing containers connect to the pre-existing external network
    `traefik-net` (`external: true`).
- **Network Routing Ambiguity Guard:**
  - Whenever a service connects to more than one network (e.g., internal
    bridge + `traefik-net`), always specify:
    ```yaml
    labels:
      - "traefik.docker.network=traefik-net"
    ```
- **Internal Service Mesh:**
  - Backends, databases, Valkey, and internal daemons communicate over a project
    bridge network (e.g., `auth-internal-net`) without exposing ports directly
    to the host.
- **Standard Websecure Labels:**
  ```yaml
  labels:
    - "traefik.enable=true"
    - "traefik.docker.network=traefik-net"
    - "traefik.http.routers.<app>.rule=Host(`${SYSTEM_DOMAIN}`)"
    - "traefik.http.routers.<app>.entrypoints=websecure"
    - "traefik.http.routers.<app>.tls=true"
    - "traefik.http.services.<app>.loadbalancer.server.port=<port>"
  ```

---

## 5. Stack Independence & Decoupling

- **Standalone Infrastructure Stacks:**
  - General-purpose infrastructure components (e.g., SPIRE, Auth-Yes, Registry
    Caches) are standalone stacks with their own dedicated project directories
    (`/volume1/docker/spire`, `/volume1/docker/auth-yes`).
  - Never nest one stack's storage or lifecycle under another stack's directory
    structure.