mirror of https://github.com/frappe/frappe_docker.git synced 2026-06-17 13:55:08 +00:00

anvie ae0a97307b update README and add wrapper script bench.sh

2025-09-25 13:49:28 +07:00

15 KiB

Raw Blame History

Frappe Docker

Production-ready containerized setup for Frappe and ERPNext applications. This repository provides Docker images and deployment configurations for running Frappe/ERPNext in both development and production environments.

Overview
Prerequisites
Quick Start
Deployment Options
Architecture
Common Tasks
Configuration
Troubleshooting
Contributing

Overview

Frappe Docker provides a complete containerized solution for deploying the Frappe framework and ERPNext ERP system. It includes:

Pre-built Docker images for Frappe and ERPNext (versions 13, 14, and 15)
Multiple deployment configurations (development, production, single-server)
Docker Compose setups for easy orchestration
Support for custom apps and extensions
Built-in backup and restore capabilities
TLS/SSL support via Traefik reverse proxy
Multi-tenancy support with port-based routing
Development containers with VSCode integration

Prerequisites

Before you begin, ensure you have:

Docker (v20.10+) - Installation Guide
Docker Compose (v2.0+) - Installation Guide
Git - Installation Guide
System Requirements:
- Minimum 4GB RAM (8GB recommended for production)
- 20GB free disk space
- Linux, macOS, or Windows with WSL2

Quick Start

Choose one of the following options to get started quickly:

Option 1: Try in Browser (Play With Docker)

Click below to instantly spin up a Frappe/ERPNext instance in your browser:

Option 2: Local Development Setup

Clone the repository:

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

Start the containers:

docker compose -f pwd.yml up -d

Wait for initialization (approximately 5 minutes)

# Monitor the setup progress
docker compose -f pwd.yml logs -f create-site

Access ERPNext:

URL: http://localhost:8080
Username: Administrator
Password: admin

Option 3: Production Setup

Clone and configure:

git clone https://github.com/frappe/frappe_docker
cd frappe_docker
cp example.env .env
# Edit .env file with your configuration

Deploy with production settings:

docker compose up -d

ARM64 Architecture Support

For ARM64 systems (Apple Silicon, Raspberry Pi):

# Build ARM64 images
docker buildx bake --no-cache --set "*.platform=linux/arm64"

# Modify pwd.yml to add platform: linux/arm64 to all services
# Then deploy
docker compose -f pwd.yml up -d

Bench Wrapper Script

To simplify working with bench commands, we provide a convenient wrapper script bench.sh that eliminates the need to type docker compose exec backend bench repeatedly.

Setup

# Make the script executable (one-time setup)
chmod +x bench.sh

Usage

The script automatically detects which compose file you're using and provides a simpler interface:

# Instead of: docker compose exec backend bench new-site mysite.local
./bench.sh new-site mysite.local

# Instead of: docker compose exec backend bench --site mysite.local migrate
./bench.sh --site mysite.local migrate

# With specific project name
./bench.sh -p erpnext-prod --site production.local backup

# Get help
./bench.sh --help

Features

Auto-detection: Automatically finds and uses the correct compose file (pwd.yml or compose.yaml)
Project support: Use -p flag for specific docker-compose projects
Full compatibility: Supports all bench commands and arguments
Error handling: Checks if containers are running before executing commands
Help system: Built-in help with common command examples

Deployment Options

Development Environment

Perfect for developers working on Frappe apps:

# Setup development environment with VSCode integration
cp -R devcontainer-example .devcontainer
cp -R development/vscode-example development/.vscode

# Open in VSCode with Dev Containers extension
code .
# Then: "Reopen in Container"

Features:

Hot-reload support
Debugging capabilities
Pre-configured VSCode settings
Multiple Python/Node versions

Production Environment

For production deployments:

# Using standard compose file
docker compose up -d

# With external database/Redis
# Configure DB_HOST, REDIS_CACHE, REDIS_QUEUE in .env
docker compose up -d

Features:

Auto-restart on failure
Health checks
Log rotation
Backup capabilities

Single Server Setup

Simplified setup for single server deployments:

docker compose -f pwd.yml up -d

This creates a complete ERPNext instance with all required services.

Architecture

The Frappe Docker setup consists of multiple interconnected services:

Core Services

Service	Purpose	Port
backend	Gunicorn application server	8000
frontend	Nginx reverse proxy	8080
websocket	Socket.io real-time server	9000
scheduler	Background job scheduler	-
queue-short	Short-running job worker	-
queue-long	Long-running job worker	-

Supporting Services

Service	Purpose	Default
db	MariaDB/PostgreSQL database	MariaDB 10.6
redis-cache	Redis cache server	Redis 6.2
redis-queue	Redis queue server	Redis 6.2

Service Flow

User Request → Nginx (frontend) → Gunicorn (backend) → Database
                ↓                      ↓
            WebSocket              Redis Cache
                                      ↓
                                  Job Queues → Workers

Common Tasks

Using the Bench Wrapper Script

For convenience, we provide a bench.sh wrapper script that simplifies running bench commands from your host machine.

# Make the script executable (first time only)
chmod +x bench.sh

# Create a new site
./bench.sh new-site mysite.local --admin-password=admin --install-app erpnext

# Run migrations
./bench.sh --site mysite.local migrate

# Backup a site
./bench.sh --site mysite.local backup

# Get help
./bench.sh --help

The script automatically detects which compose file you're using and handles the docker compose execution for you.

Site Management

Create a new site

Using wrapper script:

./bench.sh new-site mysite.local \
  --mariadb-user-host-login-scope=% \
  --db-root-password=admin \
  --admin-password=admin \
  --install-app erpnext

Or directly with docker compose:

docker compose exec backend bench new-site mysite.local \
  --mariadb-user-host-login-scope=% \
  --db-root-password=admin \
  --admin-password=admin \
  --install-app erpnext

List all sites

Using wrapper script:

./bench.sh --site all list-apps

Or directly:

docker compose exec backend bench --site all list-apps

Migrate a site

Using wrapper script:

./bench.sh --site mysite.local migrate

Or directly:

docker compose exec backend bench --site mysite.local migrate

Backup a site

Using wrapper script:

./bench.sh --site mysite.local backup

Or directly:

docker compose exec backend bench --site mysite.local backup

App Management

Install an app

Using wrapper script:

# Get the app
./bench.sh get-app https://github.com/frappe/app_name

# Install on site
./bench.sh --site mysite.local install-app app_name

Or directly:

# Get the app
docker compose exec backend bench get-app https://github.com/frappe/app_name

# Install on site
docker compose exec backend bench --site mysite.local install-app app_name

Update apps

Using wrapper script:

./bench.sh update --pull --apps

Or directly:

docker compose exec backend bench update --pull --apps

Database Operations

Access MariaDB console

docker compose exec db mysql -uroot -padmin

Import database

Using wrapper script:

./bench.sh --site mysite.local --force restore path/to/backup.sql.gz

Or directly:

docker compose exec backend bench --site mysite.local \
  --force restore path/to/backup.sql.gz

Monitoring & Logs

View all logs

docker compose logs -f

View specific service logs

docker compose logs -f backend
docker compose logs -f frontend

Check service health

docker compose ps
docker compose exec backend healthcheck.sh

Security & SSL

Setup Let's Encrypt SSL

# Configure in .env
LETSENCRYPT_EMAIL=your@email.com
SITES=`yourdomain.com`

# Deploy with Traefik
docker compose -f compose.yaml -f overrides/compose.https.yaml up -d

Configuration

Environment Variables

Create a .env file from the example:

cp example.env .env

Key configuration options:

Variable	Description	Default
`ERPNEXT_VERSION`	ERPNext version to deploy	`v15.69.2`
`DB_PASSWORD`	Database root password	`123`
`DB_HOST`	External database host	-
`REDIS_CACHE`	External Redis cache URL	-
`REDIS_QUEUE`	External Redis queue URL	-
`HTTP_PUBLISH_PORT`	HTTP port	`8080`
`FRAPPE_SITE_NAME_HEADER`	Site resolution header	`$$host`

Custom Apps Configuration

To include custom apps, create apps.json:

[
  {
    "url": "https://github.com/frappe/erpnext",
    "branch": "version-15"
  },
  {
    "url": "https://github.com/yourusername/custom-app",
    "branch": "main"
  }
]

Build custom image:

export APPS_JSON_BASE64=$(base64 -i apps.json)
docker buildx bake -f docker-bake.hcl custom

Multi-tenancy Setup

For hosting multiple sites on different ports:

# compose.override.yml
services:
  frontend:
    ports:
      - "8081:8080" # Site 1
      - "8082:8080" # Site 2

Advanced Features

Backup Automation

Setup automated backups to S3:

# Create backup script
docker compose exec backend push_backup.py \
  --site-name mysite.local \
  --bucket my-bucket \
  --region-name us-east-1 \
  --endpoint-url https://s3.amazonaws.com \
  --aws-access-key-id KEY \
  --aws-secret-access-key SECRET

Custom Build Arguments

Build with specific versions:

docker buildx bake \
  --set "*.args.FRAPPE_VERSION=v15.0.0" \
  --set "*.args.ERPNEXT_VERSION=v15.0.0" \
  --set "*.args.PYTHON_VERSION=3.11.6" \
  --set "*.args.NODE_VERSION=18.18.2"

Development with Bench

Inside development container:

# Create new bench
bench init --skip-redis-config-generation frappe-bench
cd frappe-bench

# Start bench
bench start

# Create new app
bench new-app my_custom_app

# Install app
bench --site mysite.local install-app my_custom_app

Troubleshooting

Container won't start

# Check logs
docker compose logs backend

# Verify configuration
docker compose config

# Restart services
docker compose restart

Site not accessible

# Check site configuration (using wrapper script)
./bench.sh --site mysite.local show-config

# Or directly
docker compose exec backend bench --site mysite.local show-config

# Verify nginx is running
docker compose exec frontend nginx -t

Database connection issues

# Test database connection (using wrapper script)
./bench.sh --site mysite.local mariadb

# Or directly
docker compose exec backend bench --site mysite.local mariadb

# Check database logs
docker compose logs db

Permission errors

# Fix permissions
docker compose exec backend chown -R frappe:frappe /home/frappe/frappe-bench

Reset admin password

# Using wrapper script
./bench.sh --site mysite.local set-admin-password newpassword

# Or directly
docker compose exec backend bench --site mysite.local set-admin-password newpassword

Documentation

Essential Guides

Production Deployment

Development

Customization

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Frappe Framework - Full-stack web framework
ERPNext - Open source ERP
Frappe Bench - CLI tool for Frappe deployments

Support

License

This project is licensed under the MIT License - see the LICENSE file for details.

15 KiB Raw Blame History

Frappe Docker

Table of Contents

Overview

Prerequisites

Quick Start

Option 1: Try in Browser (Play With Docker)

Option 2: Local Development Setup

Option 3: Production Setup

ARM64 Architecture Support

Bench Wrapper Script

Setup

Usage

Features

Deployment Options

Development Environment

Production Environment

Single Server Setup

Architecture

Core Services

Supporting Services

Service Flow

Common Tasks

Using the Bench Wrapper Script

Site Management

Create a new site

List all sites

Migrate a site

Backup a site

App Management

Install an app

Update apps

Database Operations

Access MariaDB console

Import database

Monitoring & Logs

View all logs

View specific service logs

Check service health

Security & SSL

Setup Let's Encrypt SSL

Configuration

Environment Variables

Custom Apps Configuration

Multi-tenancy Setup

Advanced Features

Backup Automation

Custom Build Arguments

Development with Bench

Troubleshooting

Container won't start

Site not accessible

Database connection issues

Permission errors

Reset admin password

Documentation

Essential Guides

Production Deployment

Development

Customization

Contributing

Related Projects

Support

License

15 KiB

Raw Blame History