ci-runner-test/AGENT.md

HomeLabDocker Repository Agent Context

This repository contains Docker Compose configurations for various self-hosted services.

Structure

Each service has its own directory containing:

• docker-compose.yaml - The Docker Compose configuration
• stack.env - Environment variables (excluded from version control via .gitignore)

Guidelines for Adding New Services

1. Environment Variables

• Always use environment variables in docker-compose.yaml for paths and sensitive values
• Environment variable format: ${VAR_NAME}
• Define default values in stack.env
• Example: ${FIRECRAWL_DATA_DIR} instead of hardcoded paths like /usr/share/devhome/firecrawl/data

2. Container Naming

• Use environment suffix for container names: container_name: service_${ENV}
• This allows running multiple environments (dev, staging, prod) simultaneously
• Always include ENV as an environment variable in stack.env

3. Health Checks

• Include healthcheck blocks for all services
• Use curl or wget for HTTP endpoints
• Example:

  healthcheck:
    test: ["CMD-SHELL", "curl -f http://localhost:3002/health || exit 1"]
    interval: 30s
    timeout: 5s
    retries: 3
    start_period: 30s
  

4. Networks

• Do NOT define networks explicitly - Docker Compose automatically creates a default bridge network
• Other configs in this project (Gitea, Authentik, Cloudflare) do NOT define networks explicitly

5. Volumes

• Use environment variables for volume paths
• Include timezone mount: /etc/localtime:/etc/localtime:ro

6. Files to Create

When adding a new service, create:

• <ServiceName>/docker-compose.yaml
• <ServiceName>/stack.env (add to .gitignore)