docker-erpnext/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Docker-based deployment of ERPNext, an open-source ERP system built on the Frappe framework. The repository provides a containerized solution for simplified installation and management of ERPNext using Docker Compose.

Repository: https://github.com/98labs/docker-erpnext

Architecture

The application uses a microservices architecture with the following key services:

• backend: Main ERPNext/Frappe worker service (frappe/erpnext-worker)
• frontend: Nginx service for serving static assets and proxying requests (frappe/erpnext-nginx)
• db: MariaDB 10.6 database service
• redis: Redis service for caching and queue management
• websocket: Socket.io service for real-time communications (frappe/frappe-socketio)
• queue-default/long/short: Worker services for handling different job queues
• scheduler: Service for scheduled tasks
• configurator: One-time service that sets up common site configuration
• create-site: One-time service that creates the initial ERPNext site

All services connect through a Docker network specified by APP_NETWORK (default: erpnext-local).

Key Configuration Files

• docker-compose.yml: Main orchestration file defining all services
• .env: Environment configuration (contains passwords and ports)
• variables.json: Deployment metadata and requirements
• src/compose.yaml: Base Frappe compose configuration template
• src/overrides/: Contains specific override configurations for different components

Environment Variables

Critical variables in .env:

• POWER_PASSWORD: Master password used by other services (default: LocalDev123!)
• APP_VERSION: ERPNext version (v12, v13, v14)
• APP_PASSWORD: Administrator password (uses $POWER_PASSWORD)
• APP_HTTP_PORT: HTTP port for web access (default: 8080)
• DB_MARIA_PASSWORD: MariaDB root password (uses $POWER_PASSWORD)
• APP_NAME: Container name prefix (default: erpnext)
• APP_NETWORK: Docker network name (default: erpnext-local)
• APP_DB_PARAM: Database parameter (v12 uses "mariadb", v13+ uses "db")
• APP_URL: Application URL (default: localhost)
• APP_USER: Administrator username (default: Administrator)

Common Development Commands

Initial Setup

# Create the Docker network (first time only)
docker network create erpnext-local

# Start the application
docker-compose up -d

Stopping the Application

docker-compose down

Viewing Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f backend

Accessing the Database

docker exec -it erpnext-db mysql -u root -p

Accessing the Backend Shell

docker exec -it erpnext-backend /bin/bash

Bench Commands (from within backend container)

# Access Frappe/ERPNext console
bench --site frontend console

# Run migrations
bench --site frontend migrate

# Clear cache
bench --site frontend clear-cache

# Backup site
bench --site frontend backup

Rebuilding After Version Change

When changing APP_VERSION in .env:

1. Stop containers: docker-compose down
2. Remove volumes: docker volume prune (CAUTION: This removes data)
3. Update .env with new version
4. Start containers: docker-compose up -d

Important Notes

• Internal Port: Port 8000 is used internally for container communication - do not change this
• External Port: The external HTTP port is configured via APP_HTTP_PORT in .env (default: 8080)
• Default Site: The default site name is "frontend" (created by create-site service)
• Database Parameter: Changes based on version - v12 uses "mariadb", v13+ uses "db"
• Restart Policy: All containers use "on-failure" restart policy for resilience
• Data Persistence: Site data is persisted in Docker volumes (sites, assets, db-data, redis-data)
• Network: All services communicate through the erpnext-local Docker network
• Default Credentials: Administrator / LocalDev123!

API Development

Complete API Ecosystem

ERPNext provides comprehensive REST APIs with 771 documented DocTypes across all modules.

API Documentation Files

• API_ENDPOINTS.md - Complete documentation of all 771 DocTypes
• API_GUIDE.md - Comprehensive usage guide with examples
• API_SECURITY.md - Security best practices and authentication methods
• NODEJS_API_CLIENT.md - Node.js/Axios client documentation

Secure API Clients

Two production-ready API clients are available:

Python Client (secure_api_client.py)

# Test Python client
python3 secure_api_client.py

# Generate API documentation
python3 generate_api_docs.py

Node.js/Axios Client (secure_api_client.js)

# Install dependencies
npm install axios dotenv

# Test Node.js client
node secure_api_client.js

# Run examples
node examples/api_examples.js

Authentication Methods (Security Ranked)

1. OAuth 2.0 (Best for third-party apps)
2. API Tokens (Recommended for APIs) - Authorization: token key:secret
3. Session Cookies (Web apps only, with CSRF protection)
4. Basic Auth (Testing only, never production)

Quick API Testing

# Environment setup
export ERPNEXT_API_KEY="your_key_here"
export ERPNEXT_API_SECRET="your_secret_here"

# Test with built-in scripts
./test_api.sh                    # Basic cURL tests
node test_env_vars.js           # Node.js environment test
python3 secure_api_client.py    # Python secure client

Common API Patterns

• List all: GET /api/resource/{DocType}
• Get one: GET /api/resource/{DocType}/{name}
• Create: POST /api/resource/{DocType}
• Update: PUT /api/resource/{DocType}/{name}
• Delete: DELETE /api/resource/{DocType}/{name}

API Discovery Tools

# Generate/update complete API documentation
python3 generate_api_docs.py

# Discover endpoints
./discover_api_endpoints.sh

Troubleshooting

Port Conflicts

If port 8080 is already in use, modify APP_HTTP_PORT in .env to a different port.

Network Issues

Ensure the Docker network exists:

docker network ls | grep erpnext-local
# If not found, create it:
docker network create erpnext-local

Version Changes

When changing ERPNext versions, you must remove existing data:

docker-compose down
docker volume prune  # WARNING: Removes all data
# Update APP_VERSION in .env
docker-compose up -d