ERPNext on Docker

Introduction

This repository provides a Docker-based deployment solution for ERPNext, an open-source ERP system built on the Frappe Framework. It simplifies the installation and initialization process using Docker Compose.

System Requirements

The following are the minimal recommended requirements:

• OS: Red Hat, CentOS, Debian, Ubuntu or other Linux OS
• Public Cloud: AWS, Azure, Google Cloud, Alibaba Cloud, and other major cloud providers
• Private Cloud: KVM, VMware, VirtualBox, OpenStack
• ARCH: Linux x86-64, ARM 32/64, Windows x86-64, IBM POWER8, x86/i686
• RAM: 8 GB or more
• CPU: 2 cores or higher
• HDD: at least 20 GB of free space
• Swap file: at least 2 GB
• Bandwidth: more fluent experience over 100M

QuickStart

Prerequisites

Ensure you have Docker and Docker Compose installed. If not, you can install them using:

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh && sh get-docker.sh
sudo systemctl enable docker
sudo systemctl start docker

# Setup docker-compose alias for Docker Compose V2
alias docker-compose='docker compose'
echo "alias docker-compose='docker compose'" >> /etc/profile.d/docker-compose.sh
source /etc/profile.d/docker-compose.sh

Install ERPNext

1. Clone the repository:

git clone --depth=1 https://github.com/98labs/docker-erpnext
cd docker-erpnext

2. Create the Docker network:

docker network create erpnext-local

3. Configure environment variables (optional): Edit the .env file to customize your deployment:

• POWER_PASSWORD: Master password for all services (default: LocalDev123!)
• APP_HTTP_PORT: HTTP port for web access (default: 8080)
• APP_VERSION: ERPNext version - v12, v13, or v14 (default: v14)
• APP_NAME: Container name prefix (default: erpnext)
• APP_NETWORK: Docker network name (default: erpnext-local)

4. Start the services:

docker-compose up -d

Usage

After deployment completes (may take a few minutes for initial setup), you can access ERPNext at: http://localhost:8080 (or your configured port)

Note: The initial setup creates the site and configures the database. Monitor progress with:

docker-compose logs -f create-site

Default Credentials

Username	Password
Administrator	LocalDev123!

Services and Ports

Service	Port	Use	Necessity
ERPNext Web	8080	Browser access to ERPNext	Required
MariaDB	3306	Database access	Required
Redis	6379	Cache and queue management	Required
WebSocket	9000	Real-time communications	Required

Common Operations

Viewing Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f backend

Accessing the Backend Shell

docker exec -it erpnext-backend /bin/bash

Bench Commands

From within the backend container:

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

# Clear cache
bench --site frontend clear-cache

# Run migrations
bench --site frontend migrate

Troubleshooting

Container fails to start

Check if the network exists:

docker network ls | grep erpnext-local

If not found, create it:

docker network create erpnext-local

Cannot access the application

• Verify all containers are running: docker-compose ps
• Check logs for errors: docker-compose logs
• Ensure port 8080 is not blocked by firewall

FAQ

Do I need to change the password before docker-compose up?

Yes, you should modify all database passwords and application passwords in the .env file for production use.

Docker running failed due to port conflict?

You should modify the APP_HTTP_PORT in the .env file and run docker-compose up -d again.

Why does ERPNext use port 8000 internally?

Port 8000 is used internally for container communication. Changing it causes errors. The external port is configured via APP_HTTP_PORT.

How do I run a different ERPNext version?

Change APP_VERSION in the .env file to v12, v13, or v14. Note: You must remove existing volumes before changing versions:

docker-compose down
docker volume prune
# Update .env
docker-compose up -d

Architecture

This deployment uses a microservices architecture with the following containers:

• backend: Main ERPNext/Frappe worker service
• frontend: Nginx service for serving static assets
• db: MariaDB 10.6 database
• redis: Redis cache and queue management
• websocket: Socket.io for real-time features
• queue-default/long/short: Background job workers
• scheduler: Scheduled tasks
• configurator: Initial configuration (runs once)
• create-site: Site creation (runs once)

Documentation

• ERPNext Documentation
• Frappe Framework Documentation
• Docker Compose Documentation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues related to:

• This Docker setup: Open an issue in this repository
• ERPNext application: Visit the ERPNext Forum
• Frappe Framework: Visit the Frappe GitHub

License

This Docker deployment configuration is open source. ERPNext is licensed under the GNU GPLv3 License.