Docker deployment

Deploy Frappe Framework using Docker containers

Overview

Docker provides a containerized deployment option for Frappe Framework, making it easier to manage dependencies and ensure consistent environments across development and production.

Prerequisites

Before deploying Frappe with Docker, ensure you have:

• Docker Engine (version 20.10 or higher)
• Docker Compose (version 2.0 or higher)
• Git for cloning repositories

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

Quick start

Get Frappe running with Docker in minutes:

1. Clone the Frappe Docker repository

   git clone https://github.com/frappe/frappe_docker
   cd frappe_docker
   
2. Start the containers

   docker compose -f pwd.yml up -d
   

   This command starts all required services including:

   • Frappe application server
   • MariaDB database
   • Redis cache and queue
   • nginx reverse proxy
3. Access your site

   After a couple of minutes, your site will be accessible at:

   http://localhost:8080
   

   Default login credentials:

   • Username: Administrator
   • Password: admin

Change the default password immediately after first login in production environments.

ARM64 architecture

For ARM-based systems (like Apple Silicon or ARM servers), follow the special setup instructions:

1. Visit the Frappe Docker repository
2. Follow the ARM64-specific instructions in the README

ARM64 images require different base images and may have slightly different build processes.

Docker compose files

The Frappe Docker repository includes several compose files for different scenarios:

Development setup

# For development with live reload
docker compose -f compose.yaml up -d

Features:

• Volume mounts for live code changes
• Debug mode enabled
• Development tools included

Production setup

# For production deployments
docker compose -f compose.prod.yaml up -d

Features:

• Optimized images
• Production-ready configuration
• Multi-worker setup

Proof of Work (pwd.yml)

# Quick test deployment
docker compose -f pwd.yml up -d

Features:

• Minimal configuration
• Fast startup
• Perfect for testing

Container architecture

Frappe Docker setup includes these services:

Application containers

• frappe-web: Runs gunicorn for serving HTTP requests
• frappe-worker-default: Processes default queue jobs
• frappe-worker-short: Handles short-running background jobs
• frappe-worker-long: Executes long-running background jobs
• frappe-scheduler: Manages scheduled tasks

Infrastructure containers

• mariadb: Database server for data persistence
• redis-cache: Redis instance for application caching
• redis-queue: Redis instance for job queuing
• nginx: Reverse proxy and static file server

Managing sites

Create a new site

Create additional sites in your Docker deployment:

docker compose exec frappe-web bench new-site mysite.localhost

List sites

View all sites in your deployment:

docker compose exec frappe-web bench --site all list-apps

Migrate sites

Run database migrations after updates:

docker compose exec frappe-web bench --site mysite.localhost migrate

Persistent data

Docker volumes ensure data persistence across container restarts:

• db-data: Database files
• redis-cache-data: Redis cache data
• redis-queue-data: Redis queue data
• sites: Site files and configurations

Always back up these volumes before performing major updates or migrations.

Updating containers

Update your Frappe Docker deployment:

1. Pull latest images

   docker compose pull
   
2. Recreate containers

   docker compose up -d
   
3. Run migrations

   docker compose exec frappe-web bench --site all migrate
   

Environment configuration

Customize your deployment using environment variables in a .env file:

# Database configuration
DB_ROOT_PASSWORD=strong_password
DB_HOST=mariadb
DB_PORT=3306

# Site configuration
SITE_NAME=mysite.localhost
ADMIN_PASSWORD=secure_password

# Application settings
DEVELOPER_MODE=0

Logs and debugging

View container logs

# All containers
docker compose logs -f

# Specific service
docker compose logs -f frappe-web

Execute commands in container

# Interactive shell
docker compose exec frappe-web bash

# Run bench commands
docker compose exec frappe-web bench --help

Production considerations

When deploying Docker in production:

1. Use production compose files: They include optimized settings
2. Set resource limits: Control memory and CPU usage per container
3. Enable restart policies: Ensure containers restart after failures
4. Configure SSL/TLS: Use Let’s Encrypt or other certificate providers
5. Monitor containers: Use tools like Prometheus and Grafana
6. Regular backups: Automate backup of volumes and databases

Troubleshooting

Containers won't start

Check Docker logs for errors:

docker compose logs

Ensure all required ports are available and not in use by other services.

Database connection errors

Verify database container is running:

docker compose ps mariadb

Check database credentials in environment variables match site configuration.

Permission errors

Ensure proper ownership on mounted volumes:

docker compose exec frappe-web chown -R frappe:frappe /home/frappe/frappe-bench/sites

Next steps

Bench tool

Learn about the bench CLI for site management

Configuration

Configure your Frappe deployment