Docker-Projects/AGENTS.md

Agent Guidelines for Docker Infrastructure Monorepo

CRITICAL: Forbidden Files

NEVER read, access, or attempt to open the following files under ANY circumstances:

• .env and ALL variants (.env.local, .env.development, .env.production, .env.*)
• .secrets/ directories at any level
• Any file in a secrets/ directory at any level
• Credential files: credentials.json, credentials.yml, credentials.yaml
• Key files: *.pem, *.key, *.p12, *.pfx, id_rsa, id_ecdsa, id_ed25519
• Files named token, tokens, .token, .tokens, password, passwords

What to do instead:

• Use .env.example files to understand required environment variables
• Ask the user to provide values explicitly if needed
• Use placeholder values when demonstrating code

This is a hard rule. No exceptions. No "just checking". If you need env info, read the .env.example file or ask the user.

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

• See CRITICAL: Forbidden Files section above — this is the highest priority rule in this repo
• 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