From 4d643bea1a875c65bcbd6eb9fbaabd811edc9f10 Mon Sep 17 00:00:00 2001 From: Thomas Kendrick Date: Sat, 20 Dec 2025 01:17:57 +0000 Subject: [PATCH] feat: add agents md --- AGENTS.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7664575 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,74 @@ +# Repository Architecture & Deployment Guide + +This document outlines the structure and deployment strategy for the Kendrick Homelab repository. It is intended to guide AI agents and developers in understanding the system's organization. + +## 1. Overview + +This repository serves as the "Infrastructure as Code" (IaC) source for a self-hosted homelab. It is designed to be consumed by **Portainer** using its Git integration feature (Stacks). + +- **Primary Goal:** specific, modular deployment of Docker services. +- **Deployment Method:** Portainer Stacks (Git Repository). +- **Orchestration:** Docker Compose. + +## 2. Directory Structure + +The repository follows a strict **Category > Service > Configuration** hierarchy. This ensures that every service is self-contained and easily locatable. + +```text +/ +├── category_name/ # e.g., "access_management", "media" +│ └── service_name/ # e.g., "authentik", "jellyfin" +│ ├── docker-compose.yml # The service definition +│ └── .env.example # (Optional) Template for environment variables +├── backups/ # Backup configurations +├── dashboards/ # Dashboard services (e.g., Homepage) +└── monitoring/ # System monitoring stack +``` + +### Naming Conventions +- **Categories:** Lowercase, snake_case (e.g., `access_management`). +- **Services:** Lowercase, hyphen-separated if needed (e.g., `core-keeper`). +- **Files:** Strictly `docker-compose.yml` for Portainer compatibility. + +## 3. Deployment Strategy (Portainer) + +Each subdirectory containing a `docker-compose.yml` is intended to be deployed as a separate **Stack** in Portainer. + +- **Repository URL:** This git repository. +- **Compose Path:** Relative path to the file (e.g., `proxies/traefik/docker-compose.yml`). +- **Environment Variables:** injected via the Portainer UI ("Environment variables" section) for each stack. Do not hardcode secrets in Git. + +## 4. Common Patterns & Configuration + +### Networking +- **External Network:** Most public-facing services connect to a pre-defined external network (typically `traefik_public` or similar) to allow the reverse proxy to route traffic to them. +- **Internal Communication:** Services within the same stack communicate via the default bridge network created by Docker Compose. + +### Reverse Proxy (Traefik/NPM) +- **Traefik:** Used as the primary ingress controller. Services use labels (e.g., `traefik.enable=true`) to expose themselves. +- **Nginx Proxy Manager (NPM):** Available as an alternative or secondary proxy in `proxies/npm`. + +### Dashboard Integration (Homepage) +- **Discovery:** Services utilize specific Docker labels (e.g., `homepage.group`, `homepage.name`) to automatically register themselves on the central dashboard. + +### Environment Variables +Common variables expected across stacks: +- `DOMAIN`: The root domain name (e.g., `example.com`). +- `CONFIG_ROOT`: Path on the host system where persistent configuration is stored. +- `PUID`/`PGID`: User and Group IDs for file permission management. + +## 5. Service Inventory + +| Category | Services Included | +|----------------------|-------------------| +| **Access Management**| Authentik | +| **Backups** | Zerobyte | +| **Container Mgmt** | Portainer | +| **Dashboards** | Homepage | +| **DNS** | AdGuard Home, DuckDNS | +| **Games** | Core Keeper | +| **Media** | ArrStack (Radarr/Sonarr etc.), Jellyfin | +| **Monitoring** | Beszel, Glances, Uptime Kuma | +| **Proxies** | Nginx Proxy Manager (NPM), Traefik | +| **Remote Access** | Cloudflared | +| **Version Control** | Gitea |