131 lines
3.9 KiB
Markdown
131 lines
3.9 KiB
Markdown
# 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
|
|
|
|
```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
|
|
|
|
- **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
|