Docker-Projects/AGENTS.md

Agent Guidelines for Docker Infrastructure Monorepo

Repository Structure

This is a Docker Compose monorepo for personal infrastructure hosting. The main focus is Docker services, with local tools in local/.

Core Infrastructure

• frontend/ - Cloudflare Tunnel (cloudflared/) and Traefik reverse proxy (traefik/)
• backend/ - Core data services (postgres/, redis/)
• mgmt/ - Management tools (portainer/, gitea/, grafana/, prometheus/, vaultwarden/, nextcloud/, authentik/)
• webapp/ - Applications (n8n/, navidrome/, it-tools/, openwebui/, qbittorrent/, super-productivity/)
• templates/ - Configuration templates
• remote/ - Remote access utilities

Local Tools

• local/openclaw/ - WhatsApp gateway CLI (Node.js project, see its own AGENTS.md)

Docker Commands

Managing Services

# Start a service
cd <service-path> && docker compose up -d

# Stop a service
cd <service-path> && docker compose down

# View logs
cd <service-path> && docker compose logs -f

# Restart a service
cd <service-path> && docker compose restart

# Update/pull latest images
cd <service-path> && docker compose pull && docker compose up -d

Network Architecture

• Traefik (frontend/traefik/) - Reverse proxy and load balancer
• Cloudflared (frontend/cloudflared/) - Cloudflare Tunnel for secure external access
• Services use Docker networks defined in their compose.yml files
• No port forwarding required on home router

Service Configuration

Environment Variables

• Copy .env.example to .env and fill in values
• Never commit .env files (gitignored)
• Use .secrets/ directory for sensitive files (gitignored)

Traefik Routing

Services exposed via Traefik use labels in compose.yml:

• traefik.enable=true
• traefik.http.routers.<name>.rule=Host(service.domain.com)

Volume Mounts

• Data volumes mounted to local directories (e.g., ./data, ./config)
• Some services use named Docker volumes
• Backup important data directories regularly

Working with OpenClaw (local/openclaw/)

This is a TypeScript Node.js 22+ project with its own tooling. If you need to work on it:

cd local/openclaw/

# Install and build
pnpm install
pnpm build

# Test commands
pnpm test                    # Run all tests
pnpm test -- src/path/file.test.ts   # Run single test
pnpm test:coverage          # Run with coverage
pnpm test:e2e              # Run e2e tests

# Lint and format
pnpm lint
pnpm lint:fix
pnpm format
pnpm format:fix

# Pre-commit: pnpm lint && pnpm build && pnpm test

For full OpenClaw guidelines, see local/openclaw/AGENTS.md.

Code Style Guidelines

Docker Compose

• Use compose.yml (not docker-compose.yml)
• Keep services focused and minimal
• Use environment files for configuration
• Mount volumes for persistent data

Scripts

• Shell scripts in scripts/ directories
• Use #!/bin/bash or #!/bin/sh shebang
• Make scripts executable with chmod +x

Python (local tools)

• Type hints preferred
• Use pyproject.toml for configuration
• Virtual environments for dependencies

TypeScript (OpenClaw only)

• ESM modules ("type": "module")
• Use node: prefix for Node.js built-ins
• Add .js extension to imports (e.g., from "./file.js")
• PascalCase for types, camelCase for functions
• Run pnpm lint before commits

Security Best Practices

• NEVER read, access, or attempt to open .env files or .secrets/ directories - These contain sensitive data
• .env and .secrets/ directories are gitignored everywhere
• Never commit credentials, API keys, or certificates
• Use Cloudflare Tunnel for external access (no port forwarding)
• Placeholders in documentation (e.g., user@example.com)
• Credentials stored outside repo in standard locations

Git Conventions

• Conventional commit messages (e.g., service: add health check)
• Group related changes by service
• Don't mix unrelated service changes in one commit
• Test Docker services start correctly after changes