Warning

Deprecated: superseded by frappe-nix. This repository is no longer actively developed. It is kept online, unarchived, for reference and for anyone who cannot use Nix.

frappe-nix covers the same ground and more: a devenv development shell (MariaDB, Redis, the Frappe runtime, asset watch, Mailpit), reproducible production builds, OCI container images, and a NixOS module for running benches in production.

Moving to frappe-nix

• New bench: install Nix with flakes enabled, then run nix run github:Avunu/frappe-nix and follow the prompts, as described in the frappe-nix README. Start the stack with devenv up, and run provision-site in a second shell to create the site.
• Existing bench: the ./frappe-bench/ directory this setup creates is a classic bench init bench. Run nix run github:Avunu/frappe-nix -- --dry-run inside it to preview the conversion, then drop --dry-run to apply it. See Migrate an existing bench.
• Data: this setup keeps the database in ./mariadb-data/, which frappe-nix does not read. Run ./bench.sh "backup" before you switch (backups land under ./frappe-bench/sites/<site>/private/backups/) and restore that backup into the new site.

The defaults below (for example the admin and 123 passwords) are for local development only. Do not use this stack in production.

frappe-bench-docker

🚀 Deploy persistent docker-powered Frappe sites without building custom images

A simplified Docker setup for Frappe and ERPNext development that provides persistent storage and easy management through convenient scripts.

✨ Features

• No Custom Images Required: Uses official frappe/bench:latest Docker image
• Persistent Storage: Your bench and data persist across container restarts
• Easy Setup: Interactive setup script to configure your environment
• Development Ready: Includes file watching, debugging, and hot reload
• Full Stack: Includes MariaDB, Redis, web server, and all Frappe services
• Print Server: Optional CUPS integration for printing functionality
• CLI Tools: Convenient scripts to run bench commands

📋 Prerequisites

Before you begin, ensure you have the following installed:

• Docker (version 20.10 or later)
• Docker Compose (version 2.0 or later)
• Git

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/Avunu/frappe-bench-docker.git
cd frappe-bench-docker

2. Run Setup

Linux/macOS:

./setup.sh

Windows (PowerShell):

.\setup.ps1

The setup script will:

• Prompt you to configure environment variables (or use defaults)
• Create necessary configuration files
• Start all Docker services
• Initialize your Frappe bench

3. Access Your Site

Once setup is complete, your Frappe site will be available at:

• URL: http://localhost:8080
• Username: Administrator
• Password: The password you set during setup (default: admin)

⚙️ Configuration

Environment Variables

The setup script creates a .env file with these configurable options:

Variable	Default	Description
FRAPPE_VERSION	version-15	Frappe version to install
FRAPPE_SITE_NAME_HEADER	development.localhost	Site name/domain
SITE_PASSWORD	admin	Administrator password
DB_ROOT_PASSWORD	123	MariaDB root password
CUPS_USER_ADMIN	lpadmin	CUPS admin username
CUPS_USER_PASSWORD	123	CUPS admin password

Manual Configuration

If you prefer to configure manually:

1. Copy the example environment file:

   cp .env.example .env

2. Edit .env with your preferred values

3. Start the services:

   docker compose up -d

🛠️ Usage

Running Bench Commands

Use the provided scripts to run bench commands:

Linux/macOS:

./bench.sh "list-apps"
./bench.sh "new-app myapp"
./bench.sh "install-app myapp"

Windows (PowerShell):

.\bench.ps1 "list-apps"
.\bench.ps1 "new-app myapp"  
.\bench.ps1 "install-app myapp"

Common Commands

# List installed apps
./bench.sh "list-apps"

# Create a new app
./bench.sh "new-app myapp"

# Install an app to your site
./bench.sh "install-app myapp"

# Update bench
./bench.sh "update"

# Migrate your site
./bench.sh "migrate"

# Access bench console
./bench.sh "console"

# Clear cache
./bench.sh "clear-cache"

Managing Services

# View running services
docker compose ps

# View logs
docker compose logs -f

# Stop all services
docker compose down

# Restart services
docker compose restart

# Rebuild and restart
docker compose up -d --build

🏗️ Architecture

This setup includes the following services:

Service	Purpose	Port
configurator	Initial setup and configuration	-
backend	Frappe web application	8000 (internal)
websocket	Real-time communications	9000 (internal)
web	Caddy reverse proxy	8080
watch	File watching for development	-
schedule	Scheduled job runner	-
worker_*	Background job workers	-
mariadb	Database server	3306 (internal)
redis-cache	Cache server	6379 (internal)
redis-queue	Queue server	6379 (internal)
cupsd	Print server (optional)	8631

Data Persistence

• Frappe Bench: ./frappe-bench/ (mounted as volume)
• Database: ./mariadb-data/ (mounted as volume)
• Configuration: ./cupsd.conf, ./printers.conf

🔧 Development

File Watching

The watch service automatically rebuilds assets when files change. This is enabled by default in development mode.

Debugging

You can attach a debugger to the running backend service. The bench is available at /home/frappe/frappe-bench inside the containers.

Custom Apps

To develop custom apps:

1. Create your app:

   ./bench.sh "new-app myapp"

2. Your app will be created in ./frappe-bench/apps/myapp

3. Install the app:

   ./bench.sh "install-app myapp"

4. Edit files in ./frappe-bench/apps/myapp - changes will be reflected immediately

🚨 Troubleshooting

Common Issues

Services won't start:

• Ensure Docker is running
• Check if ports 8080 or 8631 are already in use
• Run docker compose logs to see error messages

Site not accessible:

• Wait a few minutes for initial setup to complete
• Check that the configurator service has finished running
• Verify the .configured file exists in ./frappe-bench/

Permission errors:

• Ensure the frappe-bench directory has correct permissions
• The setup handles this automatically, but manual intervention may be needed

Database connection errors:

• Verify MariaDB service is running: docker compose ps mariadb
• Check database logs: docker compose logs mariadb

Resetting Everything

To start fresh:

# Stop all services
docker compose down

# Remove all data (⚠️ This will delete your database and bench!)
sudo rm -rf frappe-bench mariadb-data .env cupsd.conf printers.conf

# Run setup again
./setup.sh

Getting Help

• Check the official Frappe documentation
• Review frappe_docker documentation
• Open an issue in this repository for setup-specific problems

📄 License

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

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

1. Fork this repository
2. Create a feature branch
3. Make your changes
4. Test the setup process
5. Submit a pull request

🙏 Acknowledgments

• Frappe Framework for the excellent framework
• frappe_docker for the base Docker setup
• The Frappe community for continued support and development