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 Cloud Native solution for simplified installation and management of ERPNext using Docker Compose.

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: websoft9).

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:

APP_VERSION: ERPNext version (v12, v13, v14)
APP_PASSWORD: Administrator password
APP_HTTP_PORT: HTTP port for web access (default: 9001)
DB_MARIA_PASSWORD: MariaDB root password
APP_NAME: Container name prefix (default: erpnext)
APP_NETWORK: Docker network name (default: websoft9)

Common Development Commands

Starting 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 /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:

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

Important Notes

Port 8000 is used internally despite appearing non-standard - changing it causes container communication errors
The default site name is "frontend" (created by create-site service)
Database parameter changes based on version: v12 uses "mariadb", v13+ uses "db"
All containers use restart policy "on-failure" for resilience
Site data is persisted in Docker volumes (sites, assets, db-data, redis-data)

3.3 KiB Raw Blame History