Custom ERPNext Docker Deployment

An interactive guide to setting up, configuring, and managing your ERPNext instance.

Setup & Run Your ERPNext Instance

1. Prerequisites

Ensure you have the following installed on your system:

  • Docker Engine
  • Docker Compose

2. Build and Run Steps

Follow these steps in your project directory. The initial setup might take a few minutes.

  1. Customize configuration files: Review and adjust `.env`, `env.config`, and `apps.txt` according to your needs.
  2. Build the Docker images: 
    docker-compose build
  3. Start the services in detached mode: 
    docker-compose up -d
  4. Monitor the initial setup logs: 
    docker-compose logs -f frappe

3. Access ERPNext

Once setup is complete, access ERPNext at http://localhost:<FRAPPE_HOST_PORT>. The default administrator password is admin. Change this immediately after your first login.

Understanding Configuration Files

This deployment relies on several key files for its configuration. Properly setting these up is crucial for a smooth operation.

`.env` File (Docker Compose Environment)

This file at your project root controls Docker Compose settings like external port mappings and provides sensitive data like AWS credentials to the `docker-compose.yml` at runtime.

Example: .env
# Host port to access ERPNext
FRAPPE_HOST_PORT=8000
# Container port (MUST match FRAPPE_INTERNAL_PORT)
FRAPPE_CONTAINER_PORT=8000

# Host port for SocketIO
SOCKETIO_HOST_PORT=9000
# Container port for SocketIO
SOCKETIO_CONTAINER_PORT=9000

# AWS Credentials & S3 Backup URL
AWS_ACCESS_KEY_ID=your_aws_access_key_id
AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key
AWS_DEFAULT_REGION=your_aws_region
S3_BACKUP_URL=s3://your-bucket/backups/

`env.config` File (Container Internal)

This file is copied into the Frappe container and defines internal settings such as the Frappe site name and the internal port Bench listens on. Scripts like `init.sh`, `backup.sh`, and `restore.sh` source this file.

Example: env.config
FRAPPE_SITE_NAME=erpnext.localhost
FRAPPE_INTERNAL_PORT=8000

`apps.txt` File (Application List)

A simple text file specifying the Frappe applications (like `erpnext`, `hrms`, etc.) to be installed during the initial site setup. List one app name per line.

Example: apps.txt
erpnext
# builder
# hrms
# Add other custom apps here

Site Operations: Backup & Restore

This deployment includes scripts for essential site operations: backing up to and restoring from an S3 bucket. These are executed inside the running `frappe` container.

📤Backup to S3

Execute the `backup.sh` script to back up the site defined in `env.config`. Ensure your AWS credentials from `.env` are correctly passed to and available within the container.

Execute Backup Command
docker exec -it <frappe_container_id> /bin/bash /home/frappe/backup.sh

📥Restore from S3 Backup

To restore a site, you'll need the unique backup identifier (often a timestamped folder name) from your S3 bucket. This action will overwrite existing data for the target site.

Execute Restore Command
docker exec -it <frappe_container_id> /bin/bash /home/frappe/restore.sh -name "YOUR_BACKUP_NAME_ON_S3"

For non-interactive (automated) workflows, add the `-y` flag to bypass the confirmation prompt:

docker exec -it <frappe_container_id> ... -name "YOUR_BACKUP_NAME_ON_S3" -y

Critical: Always verify Frappe/ERPNext application version compatibility with the backup. It's highly recommended to test restore procedures in a non-production environment first.

Deployment Strategies & Environment Variables

This section explains the flow of environment variables and provides a guide for deploying your Frappe application using a platform like Dokploy, including task scheduling for automation.

Understanding Environment Variable Flow

Environment variables are crucial for configuring your application without hardcoding values. Here’s a visual overview of their typical path in this setup:

📄

.env File

(Project Root)

→
🛠️

docker-compose.yml

(Reads from .env, passes to containers)

→
📦

Containers

(e.g., Frappe)

Hover over elements to see them "interact". The `env.config` file is handled differently, copied directly into the container and sourced by internal scripts.

  • `.env` file: Located at your project root, Docker Compose uses it. Variables like `FRAPPE_HOST_PORT` and `AWS_ACCESS_KEY_ID` are substituted into `docker-compose.yml`.
  • `env.config` file: Copied into the `frappe` container. Scripts such as `init.sh`, `backup.sh`, `restore.sh` source this for site-specific settings like `FRAPPE_SITE_NAME`.
  • Passing to Containers: Your `docker-compose.yml` explicitly passes variables from `.env` (or the host environment) to services using `environment` or `env_file` directives.
    Example in docker-compose.yml:
    services:
  frappe:
    environment:
      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
      # ... other AWS vars
      - S3_BACKUP_URL=${S3_BACKUP_URL}

Deployment platforms like Dokploy often offer a UI to manage these environment variables securely, which will override or supplement your local `.env` file for the production/staging environment.

Deploying Frappe on Dokploy

Dokploy offers a streamlined way to deploy Dockerized applications. Here’s a general workflow for this Frappe setup:

  1. 1. Prepare Your Repository:

    Ensure your complete project (including `Dockerfile`, `docker-compose.yml`, all scripts, and configuration files) is pushed to a GitHub (or similar Git) repository.

  2. 2. Dokploy Project Setup:
    • In your Dokploy dashboard, initiate the creation of a new application/project.
    • Opt to deploy from a Git repository and link Dokploy to your GitHub account.
    • Choose the repository containing your Frappe project and select the desired branch.
  3. 3. Compose Services & Build Settings:
    • Dokploy should automatically detect your `docker-compose.yml` file.
    • Confirm that the build context is correctly set (typically the root of your repository).
    • Dokploy will then build custom images (like `frappe`) from your `Dockerfile` and pull standard images (MariaDB, Redis) as specified.
  4. 4. Configure Environment Variables in Dokploy:
    • Utilize Dokploy's interface to securely set environment variables (e.g., `AWS_ACCESS_KEY_ID`, `S3_BACKUP_URL`). This is the recommended practice for production secrets over committing them to your repository.
    • Variables defined in Dokploy will override those in your local `.env` or `docker-compose.yml` for the deployed instance.
    • Settings from `env.config` (like `FRAPPE_SITE_NAME`) are typically used as-is from your repo, unless your internal scripts are designed to prioritize OS environment variables.
  5. 5. Persistent Storage & Ports:
    • Configure persistent volume mounts within Dokploy for `frappe-data` and `mariadb-data` as defined in `docker-compose.yml`.
    • Set up necessary port mappings to expose your ERPNext application to the web.
  6. 6. Deploy:

    Initiate the deployment process. Dokploy will manage pulling your code, building images, and launching services.

  7. 7. Using the Scheduler for Backup/Restore Scripts:
    • Leverage Dokploy's cron job or task scheduling capabilities.
    • Set up a scheduled task to execute `backup.sh` at regular intervals. A typical command: 
      docker exec <dokploy_frappe_container_name> /bin/bash /home/frappe/backup.sh
      (Adapt container name based on Dokploy's assignment.)
    • Restores are generally manual due to their critical nature; automate with extreme caution.
    • Ensure all necessary environment variables (especially AWS credentials) are correctly available to the container environment when these scheduled tasks run.

Important: The precise user interface and steps within Dokploy can vary. Always refer to the official Dokploy documentation for the most current and detailed instructions.

Core Technical Details

Directory Structure

A quick overview of the key files and folders in this project:

  • 📁 . (Project Root)
    • 📄 Dockerfile
    • 📄 docker-compose.yml
    • 📄 init.sh
    • 📄 apps.txt
    • 📄 backup.sh
    • 📄 restore.sh
    • 📄 env.config
    • 📄 .env
    • 📄 README.md

Persistent Data Management

To ensure data is not lost when containers are stopped or removed, this setup uses Docker volumes:

  • frappe-data: Stores ERPNext site files (public, private) and critical bench configuration.
  • mariadb-data: Persists all MariaDB database data.

To remove containers AND their persistent data volumes (this is destructive):

docker-compose down -v

Troubleshooting & Logs

If you encounter issues, checking the service logs is the primary step for diagnosis:

# Check the Frappe application service logs
docker-compose logs frappe

# Check the MariaDB database service logs
docker-compose logs mariadb

# Check the Redis cache service logs
docker-compose logs redis

Ensure port configurations in `.env` and `env.config` are consistent and ports are not already in use on your host machine.