Docker Development Setup - Frappe Helpdesk

Docker provides a quick and isolated way to set up Frappe Helpdesk for development without installing dependencies directly on your system.

Prerequisites

Ensure you have the following installed:

Docker (20.10 or higher)
Docker Compose (v2.0 or higher)
Git

Refer to the Docker documentation for installation instructions specific to your operating system.

Quick Start

Create project directory

Create a new directory for your Helpdesk development environment:

mkdir frappe-helpdesk
cd frappe-helpdesk

Download Docker configuration

Download the required Docker files from the repository:

# Download docker-compose file
wget -O docker-compose.yml https://raw.githubusercontent.com/frappe/helpdesk/develop/docker/docker-compose.yml

# Download initialization script
wget -O init.sh https://raw.githubusercontent.com/frappe/helpdesk/develop/docker/init.sh

View docker-compose.yml structure

The compose file includes three services:

mariadb: Database server (MariaDB 10.8)
redis: Cache and queue backend (Redis Alpine)
frappe: Frappe application server with Bench

Start the containers

Launch all services in detached mode:

docker compose up -d

This command:

Downloads the required Docker images
Creates containers for MariaDB, Redis, and Frappe
Runs the initialization script
Sets up the Helpdesk site

The first run may take several minutes as it needs to download images, install dependencies, and initialize the database.

Access the application

Once the containers are running, access Frappe Helpdesk at:

http://helpdesk.localhost:8000/helpdesk

Default credentials:

Username: Administrator
Password: admin

Container Architecture

The Docker setup includes three interconnected services:

MariaDB Container

Image: mariadb:10.8
Configuration:
- Character set: utf8mb4
- Collation: utf8mb4_unicode_ci
- Root password: 123 (for development only)
Persistent storage: mariadb-data volume

Redis Container

Image: redis:alpine
Purpose: Caching, background job queues, and real-time updates

Frappe Container

Image: frappe/bench:latest
Exposed ports:
- 8000: Web server (Frappe backend)
- 9000: SocketIO server (real-time updates)
Working directory: /home/frappe
Volume mount: Current directory mounted to /workspace

Development Workflow

Viewing logs

Monitor container logs in real-time:

# All services
docker compose logs -f

# Specific service
docker compose logs -f frappe

Executing commands in containers

Run commands inside the Frappe container:

# General format
docker compose exec frappe <command>

# Examples
docker compose exec frappe bench --site helpdesk.localhost migrate
docker compose exec frappe bench --site helpdesk.localhost console
docker compose exec frappe bench build --app helpdesk

Accessing the container shell

Get a bash shell inside the Frappe container:

docker compose exec frappe bash

Once inside, you can run bench commands directly:

bench status
bench version
bench --site helpdesk.localhost list-apps

Restarting services

Restart specific services after configuration changes:

# Restart all services
docker compose restart

# Restart specific service
docker compose restart frappe

Stopping and starting

# Stop all containers
docker compose stop

# Start containers
docker compose start

# Stop and remove containers
docker compose down

# Stop and remove containers + volumes
docker compose down -v

Frontend Development

To develop the Vue 3 frontend with hot module replacement:

Access the container

docker compose exec frappe bash

Navigate to frontend directory

cd apps/helpdesk/desk

Install dependencies

yarn install

Start dev server

yarn dev --host helpdesk.localhost

The Vite dev server will be available on port 8080.

You may need to expose port 8080 in your docker-compose.yml file:

frappe:
  ports:
    - 8000:8000
    - 9000:9000
    - 8080:8080  # Add this line

After modifying, restart the containers: docker compose restart frappe

Database Access

Connect to MariaDB directly:

# Using docker exec
docker compose exec mariadb mysql -u root -p123

# Or from the host (if MariaDB port is exposed)
mysql -h 127.0.0.1 -u root -p123

Redis Access

Connect to Redis CLI:

docker compose exec redis redis-cli

Persistence and Data

Data volumes

The setup creates a Docker volume for MariaDB:

# List volumes
docker volume ls

# Inspect volume
docker volume inspect frappe-helpdesk_mariadb-data

Backing up data

Create a backup of your site:

docker compose exec frappe bench --site helpdesk.localhost backup

Backup files are stored in /home/frappe/frappe-bench/sites/helpdesk.localhost/private/backups/

Restoring data

Restore from a backup:

docker compose exec frappe bench --site helpdesk.localhost restore /path/to/backup

Customizing the Setup

Environment variables

Create a .env file in your project directory:

# .env
MYSQL_ROOT_PASSWORD=your_secure_password
FRAPPE_SITE_NAME=helpdesk.localhost

Then reference in docker-compose.yml:

mariadb:
  environment:
    MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}

Custom domain

To use a custom domain instead of helpdesk.localhost:

Update your /etc/hosts file:
```
127.0.0.1  myapp.local
```

Modify the initialization script or create a site manually:

docker compose exec frappe bench new-site myapp.local
docker compose exec frappe bench --site myapp.local install-app helpdesk

Common Development Tasks

Install additional apps

docker compose exec frappe bash
bench get-app https://github.com/frappe/erpnext
bench --site helpdesk.localhost install-app erpnext

Clear cache

docker compose exec frappe bench --site helpdesk.localhost clear-cache

Rebuild assets

docker compose exec frappe bench build --app helpdesk

Run tests

docker compose exec frappe bench --site helpdesk.localhost run-tests --app helpdesk

Update Frappe Framework

docker compose exec frappe bash
cd apps/frappe
git pull
bench --site helpdesk.localhost migrate

Troubleshooting

Container won’t start

Check logs for errors:

docker compose logs frappe

Port already in use

Modify ports in docker-compose.yml:

frappe:
  ports:
    - "8001:8000"  # Use 8001 instead of 8000
    - "9001:9000"

Permission errors

The Frappe container runs as the frappe user. If you encounter permission issues with mounted volumes:

# Fix ownership
docker compose exec -u root frappe chown -R frappe:frappe /workspace

Database connection errors

Ensure all containers are running:

docker compose ps

Verify network connectivity:

docker compose exec frappe ping mariadb
docker compose exec frappe ping redis

Out of memory errors

Increase Docker Desktop memory allocation in Settings > Resources.

Performance Optimization

Enable BuildKit

For faster builds, enable Docker BuildKit:

export DOCKER_BUILDKIT=1
export COMPOSE_DOCKER_CLI_BUILD=1

Volume mount performance (macOS/Windows)

On macOS and Windows, Docker volume performance can be slow. Consider using named volumes for better performance:

volumes:
  - frappe-apps:/home/frappe/frappe-bench/apps

Next Steps

Explore the Architecture Overview to understand the system design
Review the Local Setup guide for non-Docker development
Check the GitHub repository for the latest updates

Setup

Extending

Contributing

​Prerequisites

​Quick Start

​Container Architecture

​MariaDB Container

​Redis Container

​Frappe Container

​Development Workflow

​Viewing logs

​Executing commands in containers

​Accessing the container shell

​Restarting services

​Stopping and starting

​Frontend Development

​Database Access

​Redis Access

​Persistence and Data

​Data volumes

​Backing up data

​Restoring data

​Customizing the Setup

​Environment variables

​Custom domain

​Common Development Tasks

​Install additional apps

​Clear cache

​Rebuild assets

​Run tests

​Update Frappe Framework

​Troubleshooting

​Container won’t start

​Port already in use

​Permission errors

​Database connection errors

​Out of memory errors

​Performance Optimization

​Enable BuildKit

​Volume mount performance (macOS/Windows)

​Next Steps

​Additional Resources

Build docs developers (and LLMs) love

Prerequisites

Quick Start

Container Architecture

MariaDB Container

Redis Container

Frappe Container

Development Workflow

Viewing logs

Executing commands in containers

Accessing the container shell

Restarting services

Stopping and starting

Frontend Development

Database Access

Redis Access

Persistence and Data

Data volumes

Backing up data

Restoring data

Customizing the Setup

Environment variables

Custom domain

Common Development Tasks

Install additional apps

Clear cache

Rebuild assets

Run tests

Update Frappe Framework

Troubleshooting

Container won’t start

Port already in use

Permission errors

Database connection errors

Out of memory errors

Performance Optimization

Enable BuildKit

Volume mount performance (macOS/Windows)

Next Steps

Additional Resources