ERPNext Docker Scripts

A collection of bash scripts to deploy and manage ERPNext on Docker Compose. The scripts handle the full lifecycle — from initial setup to custom image builds and deployments.

Prerequisites

Install Docker Engine on Ubuntu: https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository

Initial Setup

1. Clone and prepare

git clone https://github.com/clicktrend/erpnext_docker_scripts.git
cd erpnext_docker_scripts
chmod +x scripts/*

2. Initialize the project

scripts/setup.sh

On first run, a .env file is created. Review and adjust the values, then set INSTALLED=true and run the script again:

scripts/setup.sh

This creates the .configs directory and clones frappe_docker into .frappe_docker.

---

Stack Setup

The deployment consists of three independent stacks that must be set up in order.

1. Traefik (Reverse Proxy)

scripts/traefik-setup.sh       # configure domain, email, and admin password
scripts/traefik-docker.sh up   # start Traefik

Point your DNS to the domain you entered. The Traefik dashboard is available at that domain — log in with admin and the password you set.

2. MariaDB

scripts/mariadb-setup.sh       # generate database password
scripts/mariadb-docker.sh up   # start MariaDB

To reinstall from scratch, delete the MariaDB volume before starting.

3. ERPNext

scripts/erpnext-setup.sh       # generate ERPNext configuration
scripts/erpnext-docker.sh up   # start ERPNext containers
scripts/erpnext-create-site.sh # create the ERPNext site (first time only)

Verify in the Traefik dashboard that the ERPNext router has been registered.

---

Custom Image

Apps are defined in apps.json and baked into the Docker image at build time. Private repos (e.g. GitLab) require an SSH deploy key.

SSH Deploy Key for Private Repos

Once on the server:

ssh-keygen -t ed25519 -C 'erpnext-build-deploy-key' -f .configs/deploy_key -N ''
cat .configs/deploy_key.pub

Add the printed public key as a read-only Deploy Key in GitLab under
Settings → Repository → Deploy keys.

The private key at .configs/deploy_key is automatically picked up by scripts/erpnext-custom-setup.sh as a Docker BuildKit secret — it is never baked into the image.

Build and Start

scripts/erpnext-custom-setup.sh   # build the custom image and generate compose config
scripts/erpnext-docker.sh down
scripts/erpnext-custom-docker.sh up

---

Deployment

To release a new version:

1. Pull latest scripts and update the frappe_docker fork:

   scripts/update.sh

2. Update apps.json if app versions changed
3. Bump ERPNEXT_CUSTOM_TAG in .env
4. Build and regenerate the compose config:

   # Standard build (uses Docker cache — fast, but may skip new app commits):
   scripts/erpnext-custom-setup.sh
   
   # Fresh build (no cache — picks up latest git commits from all apps):
   scripts/erpnext-custom-setup.sh --fresh

   Use --fresh whenever you pushed new commits to a custom app (e.g. adomio). Without --fresh, Docker may reuse the cached git-clone layer and miss your changes.

5. Restart ERPNext:

   scripts/erpnext-custom-docker.sh restart

6. Run migrations and rebuild assets:

   scripts/erpnext-backend.sh bench migrate
   scripts/erpnext-backend.sh bench build

7. Restart again to apply the build:

   scripts/erpnext-custom-docker.sh restart

---

Stack Management

Each stack supports up, down, logs, and restart:

scripts/traefik-docker.sh up|down|logs|restart
scripts/mariadb-docker.sh up|down|logs|restart
scripts/erpnext-custom-docker.sh up|down|logs|restart

---

Running Bench Commands

Use erpnext-backend.sh to run bench inside the running backend container:

scripts/erpnext-backend.sh bench --site erp.example.com list-apps
scripts/erpnext-backend.sh bench --site erp.example.com install-app hrms
scripts/erpnext-backend.sh bench --site erp.example.com migrate
scripts/erpnext-backend.sh bench --site erp.example.com build