# Container Architecture

# Container Architecture

The Flora Family homelab relies on a standardized Docker deployment pattern to ensure security, portability, and ease of management.

## 📂 Directory Layout
To maintain a clean separation between configuration and state, Terra uses two primary directories:

*   **/srv/[service-name]/**: Contains `docker-compose.yaml` and `.env` files. 
    *   *Ownership:* `root:root` (Modified only via sudo).
    *   *Permissions:* folders `755`, configs `644`, .env `600`.
*   **/main/appdata/[service-name]/**: Contains persistent application data.
    *   *Ownership:* Mapped to the specific service account (UID/GID).
    *   *Permissions:* `755` (folders) / `644` (files) generally.

## 🛠️ Deployment Standards

### 🔐 Non-Root Execution
Every service is configured to run as a non-privileged user, with the specific exceptions of **Watchtower** and **Beszel Agent** (which require root/host socket access to monitor system health and container status).

Non-root execution is achieved through one of three methods:

1.  **Standard `user:` flag**: For images that support it (e.g., `user: "51100:61100"`).
2.  **Environment Variables**: Many linuxserver.io images use `PUID`/`PGID` variables.
3.  **Custom Dockerfile Builds**: Used for "scratch" images or minimalist images (like OpenWebUI and SearXNG) to manually inject the desired UID/GID and install local CA certificates.

### 🔗 Shared Infrastructure
Common backend services are standardized to simplify inter-container networking and permissions:

*   **Postgres:** Standardized on GID `70` across all instances (Immich, n8n, etc.).
*   **Redis/Valkey:** Standardized on GID `970` for caching and session management.
*   **Shared Identities:** The `node-user` (UID 1000) is shared between several JS-based apps (n8n, Uptime Kuma) where common file access is required.

## 🔄 Lifecycle Management
*   **Updates:** Managed by **Watchtower**, configured to run every Sunday at 04:00 AM.
*   **Image Tagging:**
    *   *Pinned:* Databases and critical infrastructure (e.g., `postgres:18`) to prevent breaking updates.
    *   *Floating:* Application layers (e.g., `sonarr:latest`) to receive automated security patches.