erp/LLM.md

ERPNext Hanzo Deployment

ERPNext v15 configured for Docker Compose deployment on Hanzo (Dokploy) platform. Self-initializing -- no manual setup required.

Stack

• App: ERPNext v15.62.0 on Frappe Framework (Python/JS)
• DB: MariaDB 10.6
• Cache/Queue: Redis 7
• Web: Nginx reverse proxy
• SSL: Traefik with Let's Encrypt
• Container: Docker Compose

Domains

• Production: erp.hanzo.ai (compose.prod.yml)
• Development: erp-dev.hanzo.ai (compose.dev.yml)

Services

Internet -> Traefik (SSL) -> Nginx :8080
                              ├── /* -> Backend :8000
                              ├── /socket.io/ -> WebSocket :9000
                              └── /assets/ -> Static Files

Backend -> MariaDB :3306
        -> Redis Cache
        -> Redis Queue

Service	Role
configurator	One-time init: creates site, installs app, enables scheduler
frontend	Nginx reverse proxy (only exposed service)
backend	Frappe/ERPNext app server
websocket	Socket.io real-time
worker-short	Short-running background jobs
worker-long	Long-running background jobs
scheduler	Cron task runner
db	MariaDB
redis-cache	Cache (LRU, 512MB)
redis-queue	Job queue (AOF persistence)

Environment Variables

Set in Hanzo UI:

• DB_PASSWORD: MariaDB root password
• ADMIN_PASSWORD: ERPNext Administrator password

File Structure

/Users/z/work/hanzo/erp/
├── compose.prod.yml       # Production config
├── compose.dev.yml        # Development config
├── erpnext/               # ERPNext application source
├── docs/                  # Deployment and routing docs
├── pyproject.toml         # Python config
└── package.json           # Node dependencies

Common Tasks

# Backup
docker exec <backend> bench --site erp.hanzo.ai backup --with-files

# Console
docker exec -it <backend> bench console

# Clear cache
docker exec <backend> bench --site erp.hanzo.ai clear-cache

# Migrations
docker exec <backend> bench --site erp.hanzo.ai migrate

Deployment

1. Set DB_PASSWORD and ADMIN_PASSWORD in Hanzo UI
2. Deploy compose file -- configurator auto-initializes everything
3. Updates: change image version tag, redeploy (migrations run automatically)

Notes for AI Assistants

• Always update both prod and dev compose files for deployment changes
• Never expose internal services directly -- frontend handles all external traffic
• All services must be on hanzo-network
• Check configurator logs first for setup issues
• Use environment variables, not hardcoded values

Rules for AI Assistants

1. ALWAYS update LLM.md with significant discoveries
2. NEVER commit symlinked files (.AGENTS.md, CLAUDE.md, etc.) -- they are in .gitignore
3. NEVER create random summary files -- update THIS file