How to Install ERPNext with Docker: Complete Step-by-Step Guide

If you want to run ERPNext using Docker, the official frappe_docker project provides a convenient way to get a Frappe application environment running without manually installing all of its dependencies on your host operating system.

The official Frappe Docker repository provides Docker images, Docker Compose configurations, and documentation for running Frappe applications such as ERPNext in containers. It supports different deployment approaches for development, testing, and production environments.

In this guide, we will use the official pwd.yml quick-start configuration to get ERPNext running with Docker.

Important: The pwd.yml setup is intended for quick evaluation and disposable environments. It is not a production deployment method and is not intended for long-term ERPNext hosting. The official Frappe Docker documentation recommends a separate production setup using compose.yaml and the appropriate overrides for production deployments.

By the end of this guide, you will know how to:

• Install the required Docker components.
• Clone the official Frappe Docker repository.
• Start the ERPNext Docker environment.
• Check the status of the containers.
• Monitor the site creation process.
• Access ERPNext from your browser.
• View container logs.
• Stop and restart the environment.
• Understand the difference between the quick demo environment and a production deployment.

---

Table of Contents

• How the Current Frappe Docker Setup Works

• Prerequisites

  • Docker
  • Docker Compose v2
  • Git

• Step 1 – Verify Docker

• Step 2 – Verify Docker Compose

• Step 3 – Verify Git

• Step 4 – Clone the Frappe Docker Repository

• Step 5 – Start ERPNext with the Official Quick-Start Configuration

• Step 6 – Wait for ERPNext Site Creation

• Step 7 – Check the Docker Containers

• Step 8 – Check the Site Creation Logs

• Step 9 – Access ERPNext

• Step 10 – Log in to ERPNext

• Step 11 – View Container Logs

• Step 12 – Stop the ERPNext Environment

• Step 13 – Start the Environment Again

• Step 14 – Remove the Quick-Start Environment

• Quick Reference Commands

• Quick Demo vs Production Deployment

• Important Limitations of the Quick-Start Setup

• Production ERPNext Deployment

• Troubleshooting

• Conclusion

---

How the Current Frappe Docker Setup Works

The official Frappe Docker repository is designed to run Frappe applications inside Docker containers.

The repository currently contains several important components, including:

frappe_docker/
├── docs/
├── overrides/
├── compose.yaml
├── pwd.yml
├── images/
├── development/
├── devcontainer-example/
└── resources/

The important files for understanding the deployment options are:

• pwd.yml — a single-file, disposable quick-start environment.
• compose.yaml — the base Compose configuration used for production deployments.
• overrides/ — additional Compose configurations used for different production scenarios.
• docs/ — the official documentation covering deployment, operations, development, and configuration.

The official documentation explicitly distinguishes these deployment methods.

For a quick evaluation, use:

pwd.yml

For production, use:

compose.yaml + appropriate overrides

This distinction is important because the quick-start environment is not intended to be converted into a production installation later.

---

Prerequisites

Before starting, make sure your system has the following:

• Docker
• Docker Compose v2
• Git
• Internet connectivity
• Sufficient disk space for Docker images and container data

The official Frappe Docker repository currently lists Docker, Docker Compose v2, and Git as prerequisites.

---

Docker

Docker provides the container runtime required to run ERPNext and its supporting services.

If Docker is not installed on your system, follow the official Docker installation documentation:

Install Docker

After installing Docker, verify it:

$ docker --version

You should receive output similar to:

Docker version ...

The exact version will depend on the Docker release installed on your system.

---

Docker Compose v2

The current Frappe Docker documentation requires Docker Compose v2.

Modern Docker installations generally provide Compose through the Docker CLI.

Check that it is available:

$ docker compose version

You should receive output similar to:

Docker Compose version v2.x.x

Important: The current official instructions use docker compose, with a space, rather than the older docker-compose command.

For example, the current command is:

$ docker compose -f pwd.yml up -d

rather than:

$ docker-compose up -d

This is an important difference from many older ERPNext Docker tutorials.

---

Git

Git is required to download the official Frappe Docker repository.

Check whether Git is installed:

$ git --version

If Git is not installed on Ubuntu, install it with:

$ sudo apt update

Then:

$ sudo apt install -y git

Verify the installation:

$ git --version

---

Step 1 – Verify Docker

Before downloading ERPNext, make sure Docker is available.

Run:

$ docker --version

Then verify Docker Compose:

$ docker compose version

Finally, verify that Docker can run containers:

$ docker run hello-world

If Docker is working correctly, Docker will download the hello-world image and run the container.

You can then continue with the ERPNext installation.

---

Step 2 – Verify Docker Compose

Run:

$ docker compose version

If the command works, Docker Compose v2 is available.

The official Frappe Docker project specifically lists Docker Compose v2 as a prerequisite.

---

Step 3 – Verify Git

Run:

$ git --version

If Git is installed, you should receive its version information.

If it is not installed on Ubuntu:

$ sudo apt update

Then:

$ sudo apt install -y git

---

Step 4 – Clone the Frappe Docker Repository

The current official quick-start process does not require you to manually create your own docker-compose.yml.

Instead, clone the official frappe_docker repository.

Run:

$ git clone https://github.com/frappe/frappe_docker

This downloads the official repository to your current directory.

Now enter the repository:

$ cd frappe_docker

You can check the contents:

$ ls

You should see files and directories including:

compose.yaml
pwd.yml
docs
overrides
images
development

The official repository identifies pwd.yml as the single-file quick-start configuration and compose.yaml as the base configuration for production deployments.

---

Step 5 – Start ERPNext with the Official Quick-Start Configuration

For a quick evaluation, the official repository provides pwd.yml.

Run:

$ docker compose -f pwd.yml up -d

Let’s break this command down:

docker compose

Runs Docker Compose.

-f pwd.yml

Tells Docker Compose to use the pwd.yml configuration file.

up

Creates and starts the services defined in the Compose file.

-d

Runs the containers in detached mode, allowing you to continue using your terminal.

The official repository currently documents this exact command for the quick demo environment.

During the first startup, Docker may need to download the required images.

You may therefore see a significant amount of output while Docker:

• Pulls container images.
• Creates networks.
• Creates volumes.
• Creates containers.
• Starts the required services.
• Creates the ERPNext site.

The current pwd.yml uses a current ERPNext Docker image, rather than the older manually specified configuration used in many previous tutorials.

---

Step 6 – Wait for ERPNext Site Creation

Starting the containers does not necessarily mean that the ERPNext site is immediately ready.

The official documentation specifically states that you should wait a couple of minutes for the ERPNext site to be created, or check the create-site container logs before opening ERPNext in your browser.

This is important.

Do not assume that the following means ERPNext is ready:

$ docker compose -f pwd.yml up -d

The containers may be running while the initial site setup is still in progress.

---

Step 7 – Check the Docker Containers

To see the containers currently running on your system, use:

$ docker ps

This displays information such as:

• Container ID
• Image
• Command
• Creation time
• Status
• Ports
• Container name

You can also inspect the Compose project:

$ docker compose -f pwd.yml ps

This provides a view of the services associated with the pwd.yml deployment.

If a service is still starting, give the environment additional time before troubleshooting.

---

Step 8 – Check the Site Creation Logs

If ERPNext does not become available after waiting a few minutes, inspect the create-site container.

First, list the containers:

$ docker ps -a

Look for the container responsible for site creation.

You can then inspect its logs using:

$ docker logs <create-site-container>

Replace:

<create-site-container>

with the actual container name.

For example:

$ docker logs frappe_docker-create-site-1

The exact generated container name may differ depending on your Docker Compose project name.

You can also follow the logs in real time:

$ docker logs -f <create-site-container>

Press:

Ctrl+C

to stop following the logs.

The official repository specifically recommends checking the create-site container logs if you need to verify whether the ERPNext site has finished being created.

---

Step 9 – Access ERPNext

Once the site has been created successfully, open your browser.

For the official quick-start setup, ERPNext is exposed on port 8080.

Open:

http://localhost:8080

If Docker is running on a remote server, replace localhost with the server’s IP address.

For example:

http://YOUR_SERVER_IP:8080

Replace:

YOUR_SERVER_IP

with the IP address of your server.

For example:

http://192.168.1.100:8080

The official repository specifies port 8080 for accessing the quick-start ERPNext environment.

---

Step 10 – Log in to ERPNext

The current official quick-start documentation provides the following credentials for the disposable demo environment:

Username:

Administrator

Password:

admin

These credentials are documented by the official Frappe Docker repository for the pwd.yml quick-start environment.

Important: These credentials are intended for the disposable demo environment. Do not use a known default password for a production deployment.

After logging in, you can explore ERPNext and familiarize yourself with the interface.

---

Step 11 – View Container Logs

Docker logs are extremely useful when troubleshooting ERPNext.

First, list your containers:

$ docker ps

Find the container you want to inspect.

Then run:

$ docker logs <container_name>

Replace:

<container_name>

with the actual container name.

For example:

$ docker logs <container_name>

To continuously follow the logs:

$ docker logs -f <container_name>

Press:

Ctrl+C

to stop following the logs.

You can also view logs through Docker Compose:

$ docker compose -f pwd.yml logs

To follow them continuously:

$ docker compose -f pwd.yml logs -f

These commands are useful when investigating:

• Startup problems.
• Database connection issues.
• Container crashes.
• Site creation failures.
• Configuration problems.
• Service dependency issues.

---

Step 12 – Stop the ERPNext Environment

When you are finished testing ERPNext, you can stop and remove the Compose containers with:

$ docker compose -f pwd.yml down

This stops the services defined by the Compose project and removes the containers and network created for the project.

Because the official pwd.yml setup is intended to be disposable, you should treat it as a temporary evaluation environment rather than a permanent ERPNext installation.

---

Step 13 – Start the Environment Again

If you have stopped the environment and want to start it again, run:

$ docker compose -f pwd.yml up -d

Check the status:

$ docker compose -f pwd.yml ps

Then check the containers:

$ docker ps

If the site needs to be recreated or initialized, allow the required containers to complete their startup process before accessing ERPNext.

---

Step 14 – Remove the Quick-Start Environment

If you are completely finished with the disposable test environment, you can remove its containers with:

$ docker compose -f pwd.yml down

You should be careful when manually removing Docker volumes.

Volumes can contain persistent application data, including database or ERPNext site data.

Do not use broad Docker cleanup commands simply to “clean up” a production server.

For example, commands such as:

$ docker system prune --all --force --volumes

can remove unused Docker resources and volumes.

Warning: --volumes makes this particularly dangerous when important persistent data is stored in Docker volumes. Never run destructive cleanup commands on a production ERPNext server without first understanding exactly what will be removed and confirming that reliable backups exist.

---

Quick Reference Commands

Clone the Repository

$ git clone https://github.com/frappe/frappe_docker

Enter the Repository

$ cd frappe_docker

Start the Quick Demo

$ docker compose -f pwd.yml up -d

Check Services

$ docker compose -f pwd.yml ps

Check Running Containers

$ docker ps

Check All Containers

$ docker ps -a

View Compose Logs

$ docker compose -f pwd.yml logs

Follow Compose Logs

$ docker compose -f pwd.yml logs -f

View a Container’s Logs

$ docker logs <container_name>

Follow a Container’s Logs

$ docker logs -f <container_name>

Stop the Quick Demo

$ docker compose -f pwd.yml down

Start the Quick Demo Again

$ docker compose -f pwd.yml up -d

---

Quick Demo vs Production Deployment

This distinction is one of the most important things to understand when using the current Frappe Docker repository.

Quick Evaluation

For quickly trying ERPNext, the official repository provides:

pwd.yml

The command is:

$ docker compose -f pwd.yml up -d

This setup is:

• Easy to start.
• Suitable for evaluation.
• Suitable for short-lived testing.
• Disposable.
• Not intended for production.
• Not intended for custom app installation.

Production Deployment

For production deployments, the official documentation identifies:

compose.yaml

together with appropriate files from:

overrides/

as the canonical manual production approach.

Production deployments require considerably more configuration than the quick demo.

Depending on your requirements, you may need to configure:

• Persistent storage.
• Database configuration.
• Redis.
• HTTPS/SSL.
• Domain names.
• Reverse proxy configuration.
• Email.
• Backups.
• Monitoring.
• Resource limits.
• Custom applications.
• Custom Docker images.
• Environment variables.
• Secrets.
• Update procedures.
• Disaster recovery.

The official Frappe Docker repository provides separate documentation for these production workflows.

---

Important Limitations of the Quick-Start Setup

The pwd.yml setup is extremely convenient, but it is important to understand what it is designed for.

The official documentation explicitly describes it as a disposable demo environment.

It should therefore be used for:

• Exploring ERPNext.
• Testing the Docker environment.
• Learning how Frappe works with Docker.
• Quickly evaluating ERPNext.
• Temporary demonstrations.

It should not be treated as your final production architecture.

The official documentation also states that you cannot install custom apps into this quick-start setup.

If you need custom Frappe applications, production configuration, or a long-running ERPNext deployment, use the production deployment approach instead.

---

Production ERPNext Deployment

If your objective is to host ERPNext for a real business, do not simply expose the pwd.yml demo environment to the internet and consider the installation complete.

The official Frappe Docker project provides a production deployment approach based on:

compose.yaml

and:

overrides/

The repository describes this as the canonical manual production deployment method.

The repository also provides an Easy Install Script through the Frappe Bench project. This automates much of the production deployment process and uses frappe_docker internally.

For a production deployment, you should follow the official production documentation rather than adapting this quick-start tutorial.

You can find the current documentation in the official repository:

Frappe Docker Documentation

---

Environment Variables

Production and customized deployments can be configured through environment variables.

The current Frappe Docker documentation supports using a .env file.

A typical starting point is:

$ cp example.env .env

You can then edit the .env file:

$ nano .env

The current environment-variable documentation includes variables such as:

FRAPPE_PATH
FRAPPE_BRANCH
ERPNEXT_VERSION
DB_PASSWORD

The exact variables required depend on the deployment method and configuration you choose.

For example, the current documentation identifies:

FRAPPE_BRANCH

as the Frappe branch and:

ERPNEXT_VERSION

as the ERPNext release version.

The database password can be supplied using:

DB_PASSWORD

or through the supported secrets-file mechanism.

Security recommendation: Do not publish passwords, database credentials, API keys, or other secrets in public repositories or articles.

---

Custom Applications

One important difference between a quick ERPNext demo and a real ERPNext deployment is custom application support.

The official Docker repository explains that the default image contains the frappe and erpnext applications.

If you need custom Frappe applications, the recommended approach is to build a custom Docker image containing those applications rather than trying to install arbitrary applications into the disposable pwd.yml environment.

This is particularly important for businesses using:

• Custom Frappe apps.
• Custom doctypes.
• Custom integrations.
• Industry-specific applications.
• HRMS.
• CRM.
• Third-party Frappe applications.
• Private applications.

For these scenarios, follow the custom image and production documentation in the official repository.

---

Troubleshooting

ERPNext Is Not Opening

First check the running containers:

$ docker ps

Then check the Compose services:

$ docker compose -f pwd.yml ps

If the site has not finished initializing, check the site creation container logs.

First list all containers:

$ docker ps -a

Then inspect the relevant container:

$ docker logs <container_name>

---

A Container Keeps Restarting

Check the container logs:

$ docker logs <container_name>

For continuously updated logs:

$ docker logs -f <container_name>

Look for errors related to:

• Database connectivity.
• Configuration.
• Missing environment variables.
• File permissions.
• Failed dependencies.
• Service startup failures.

---

Check All Compose Logs

Run:

$ docker compose -f pwd.yml logs

For live output:

$ docker compose -f pwd.yml logs -f

---

Check Container Status

Run:

$ docker ps -a

This displays both running and stopped containers.

You can also inspect the Compose project:

$ docker compose -f pwd.yml ps

---

Check Docker Resources

If you suspect a disk-space problem, check Docker’s disk usage:

$ docker system df

This shows information about:

• Images.
• Containers.
• Local volumes.
• Build cache.

Do not immediately run aggressive cleanup commands on a production system.

---

Security Considerations

If you are using the quick-start environment only for local testing, the default configuration may be sufficient for evaluation.

For production, however, you need to consider security from the beginning.

At minimum, a production deployment should address:

• Strong administrator credentials.
• HTTPS.
• Firewall configuration.
• Secure database credentials.
• Secrets management.
• Regular backups.
• Restricted access to administrative services.
• Monitoring.
• Security updates.
• Disaster recovery.

Most importantly, do not expose a disposable demo environment directly to the public internet and treat it as a production ERPNext installation.

The official Frappe Docker project intentionally separates the quick demo setup from production deployment for this reason.

---

Conclusion

Running ERPNext with Docker has become significantly simpler with the official Frappe Docker project.

For a quick evaluation, the current process is:

$ git clone https://github.com/frappe/frappe_docker

Then:

$ cd frappe_docker

And finally:

$ docker compose -f pwd.yml up -d

After the containers start, wait for the ERPNext site to be created. The official documentation recommends checking the create-site container logs if necessary. Once the site is ready, access ERPNext at:

http://localhost:8080

The documented quick-start credentials are:

Username: Administrator
Password: admin

However, there is an important distinction between trying ERPNext with Docker and running ERPNext in production.

The pwd.yml configuration is designed as a disposable quick-start environment. For production deployments, the official Frappe Docker documentation recommends using the production-oriented compose.yaml together with the appropriate overrides, or using the Easy Install approach.

If your goal is simply to evaluate ERPNext, the quick-start setup is an excellent way to get started.

If your goal is to run ERPNext for an actual business, host multiple customers, install custom applications, or build a reliable long-term ERPNext infrastructure, you should move to the official production deployment architecture instead.