# 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:
  ```yaml
  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)