Brian Tan Seng 44a463d99c Updated all documentation based on the work done so far. Here's a summary of the

documentation updates:

  Updated Files:

  1. CLAUDE.md - Enhanced with:
    - Added repository URL
    - Updated environment variables section with complete list
    - Added initial setup instructions with network creation
    - Fixed container names (e.g., erpnext-backend)
    - Added comprehensive troubleshooting section
    - Updated default port to 8080
  2. README.md - Completely revamped with:
    - Added links to ERPNext and Frappe Framework
    - Improved prerequisites section
    - Added note about initial setup time
    - Enhanced services table with all key services
    - Added architecture section describing all containers
    - Added troubleshooting section
    - Added contributing and support sections
    - Better formatted installation instructions
  3. Notes.md - Completely rewritten with:
    - Architecture overview
    - Installation process explanation
    - Key configuration files documentation
    - Common operations guide
    - Version differences (v12 vs v13+)
    - Performance tuning tips
    - Security considerations
    - Removed obsolete Chinese content
  4. CHANGELOG.md - Added comprehensive changelog:
    - Documented all websoft9 removal changes
    - Listed all documentation improvements
    - Tracked network name change to erpnext-local
  5. .env.example - Created new example file:
    - Clear documentation of all environment variables
    - Secure default password placeholder
    - Comments explaining each variable
    - Proper structure matching actual .env

  All documentation now accurately reflects:
  - The erpnext-local network usage
  - Port 8080 as default
  - No websoft9 dependencies
  - Clear installation instructions
  - Comprehensive troubleshooting guides

2025-08-22 16:57:56 +08:00

3.3 KiB

Raw Blame History

ERPNext Docker Deployment Notes

Architecture Overview

ERPNext uses a microservices architecture with multiple containers working together:

Backend worker services (Frappe/ERPNext)
Frontend Nginx service
MariaDB database
Redis for caching and queues
WebSocket service for real-time features
Queue workers for background jobs
Scheduler for periodic tasks

Installation Process

The installation is automated through Docker Compose:

Environment Configuration: The .env file contains all necessary configuration variables
Network Setup: Uses a dedicated Docker network (erpnext-local) for container communication
Service Orchestration: The docker-compose.yml file orchestrates all services
Initial Setup: The configurator and create-site services handle initial configuration

Key Configuration Files

docker-compose.yml

Main orchestration file that defines all services and their relationships.

.env

Environment variables including:

POWER_PASSWORD: Master password
APP_VERSION: ERPNext version (v12, v13, v14)
APP_HTTP_PORT: External HTTP port
APP_NETWORK: Docker network name

src/compose.yaml

Base Frappe compose configuration template.

src/overrides/

Contains specific override configurations for different components:

compose.erpnext.yaml: ERPNext-specific overrides
compose.redis.yaml: Redis configuration
compose.mariadb.yaml: MariaDB configuration

Common Operations

Creating a New Site (Manual)

If you need to create additional sites:

docker compose exec backend bench new-site <site-name> --mariadb-root-password <password> --admin-password <admin-password>

Backup and Restore

# Backup
docker compose exec backend bench --site frontend backup

# Restore
docker compose exec backend bench --site frontend restore <backup-file>

Version Differences

v12

Uses mariadb as database parameter
Older UI and features

v13+

Uses db as database parameter
Modern UI with improved features
Better performance

Troubleshooting

Image Issues

If images appear broken, ensure the frontend service is running and properly configured.

Port 8000

Internal port 8000 is hardcoded in ERPNext - do not change it. Use APP_HTTP_PORT for external access.

Site Creation

The default site is named "frontend" and is created automatically by the create-site service.

Performance Tuning

Memory Requirements

Minimum: 4GB RAM
Recommended: 8GB+ RAM for production

Database Optimization

MariaDB configuration can be tuned via environment variables or custom configuration files.

Redis Configuration

Redis is used for caching and queue management. Default configuration is suitable for most deployments.

Security Considerations

Change Default Passwords: Always change the default POWER_PASSWORD in production
Network Isolation: The erpnext-local network provides isolation between containers
SSL/TLS: Consider using a reverse proxy (nginx/traefik) for SSL termination in production
Firewall Rules: Only expose necessary ports (typically just the HTTP port)

3.3 KiB Raw Blame History