erpnext dev container

One click containerized environment for ERPNext Development

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Features
5. Contributing
6. License
7. Contact

About The Project

ERPNext Dev Container is a single-container Docker setup for Frappe/ERPNext v15 development. It initializes a complete bench on first run, installs configured apps, creates a site, and provides a fast, repeatable workflow for local development on macOS, Linux, and Windows with Docker Desktop.

(back to top)

Built With

(back to top)

Getting Started

Prerequisites

• Docker Desktop with Compose v2
• At least 4 GB RAM available to Docker
• 10+ GB free disk space

Installation

1. Clone the repository

   git clone https://github.com/washmoredevelopment/erpnext-dev-container.git
   cd erpnext-dev-container

2. Copy the example environment file

   cp env.example .env

3. (Optional) Edit .env:

   • SITE_NAME (default: development.localhost)
   • DB_ROOT_PASSWORD
   • ADMIN_PASSWORD
   • SSH_KEY_PATH (for private repos)

4. Build and start

   docker compose build
   docker compose up -d

5. First run takes ~10–15 minutes to initialize

6. After installation completes, restart

   docker compose down
   docker compose up -d

7. Access ERPNext: http://localhost:8000

   • Username: Administrator
   • Password: value of ADMIN_PASSWORD (default admin)

(back to top)

Usage

Container management

docker compose up -d      # start
docker compose down       # stop
docker compose logs -f    # logs

Shell and bench

docker compose exec frappe zsh
docker compose exec frappe zsh -lc "cd /home/frappeuser/frappe-bench && bench <command>"

Container health

# Check container health
docker ps  # Shows health: starting/healthy/unhealthy

# View detailed health status
docker exec -it frappe-dev cat /tmp/container_health

# Manual health check
docker exec -it frappe-dev /usr/local/bin/health-check

(back to top)

Features

• Single-container setup on Ubuntu 24.04 LTS
• Flexible app configuration via APPS in docker-compose.yml
• Optional private repo access via SSH_KEY_PATH
• All dependencies included (MariaDB, Redis, Python, Node)
• Developer mode and bench watch enabled
• Persistent volumes: frappe-data and frappe-mysql
• Health checks with clear status and logs
• ARM64 and AMD64 supported

(back to top)

Contributing

Contributions are welcome. If you have ideas or find issues, please open an issue or submit a pull request.

1. Fork the project
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Questions or feedback? Please open an issue on GitHub.

Repo: https://github.com/washmoredevelopment/erpnext-dev-container

(back to top)