# 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

```bash
# 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:

```bash
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