[Guide] Frappe Docker Bootstrapper For Developer (version-13,14,15,16) compatibility

Install / Update Setup
1

:rocket: Frappe Docker Bootstrapper

License: MIT
Docker
Frappe

One‑command, Docker‑based Frappe development environments – fully isolated, version‑selectable, and ready for VS Code DevContainers.

Stop wasting time on manual setup. This repository provides two bash scripts that spin up a complete Frappe development stack (Frappe + MariaDB + Redis) inside Docker, with automatic Python, Node, and Yarn version management. Perfect for multi‑project developers, contributors, or anyone who wants a pristine Frappe environment in minutes.

:sparkles: Features

  • Choose your Frappe version – version-13 / 14 / 15 / 16 / develop
    (the setup_frappe16.sh script locks to v16 with Python 3.14.0 and Node 24)
  • Fully isolated per project – each project gets its own containers, volumes, ports, and Redis instances – no conflicts, even when running multiple projects simultaneously.
  • Automatic environment setup inside the container – pyenv, nvm, and corepack handle Python, Node, and Yarn versions seamlessly.
  • One‑command bench initialization – bench init, site creation, developer mode, and optional ERPNext installation.
  • Ready for VS Code DevContainers – the generated project includes a .devcontainer folder; just reopen in container for a full IDE experience.
  • Helper scripts – start.sh, stop.sh, console.sh, status.sh – manage your environment effortlessly.
  • No sudo needed – everything runs inside the Docker container; your host stays clean.

:clipboard: Prerequisites

Make sure you have the following installed on your system:

:hammer_and_wrench: Quick Start

  1. Clone this repository

    git clone https://github.com/pra11shant/frappe-docker-bootstrapper.git
cd frappe-docker-bootstrapper

  2. Make the scripts executable

    chmod +x *.sh

  3. Run the bootstrapper that fits your needs

  • For Frappe v16 (fixed versions):

    ./setup_frappe16.sh

  • For Frappe v13–v15 or develop (version selection):

    ./setup.sh

  1. Follow the interactive prompts – you’ll be asked for:

    • Project name (e.g., myapp)
    • Install ERPNext? (y/n)
    • Base web port (e.g., 8010) – the socket port will be automatically set to port+1000
    • image

  2. Wait – the script will:

    • Clone frappe_docker
    • Create and start the Docker containers
    • Install Python, Node, and Yarn inside the container
    • Initialize the bench, create a site, enable developer mode, and optionally install ERPNext
    • Generate helper scripts and a PROJECT_INFO.md file
    • Finally like this image

  3. Start developing

    cd your-project-name
./start.sh   # starts the bench inside the container

Visit http://your-project.localhost:8010 (or the port you chose) – default admin password is admin.
image

:open_file_folder: Project Structure (generated per project)

  your-project/
  ├── .devcontainer/
  │   ├── docker-compose.yml   # services definition
  │   └── devcontainer.json    # VS Code configuration
  ├── development/             # bench will be created here
  ├── .env                     # environment variables
  ├── start.sh                 # start bench
  ├── stop.sh                  # stop containers
  ├── restart.sh               # restart containers
  ├── console.sh               # open bash inside frappe container
  ├── status.sh                # show running containers
  ├── vscode.sh                # open project in VS Code
  └── PROJECT_INFO.md          # summary of your project (ports, credentials, paths)

:technologist: Using VS Code DevContainer

  1. Open the generated project folder in VS Code.
  2. Press Cmd+Shift+P (or Ctrl+Shift+P) and select Dev Containers: Reopen in Container.
  3. VS Code will rebuild the container and attach to it – you can now edit code, run bench commands, and debug directly inside the environment.

:wrench: Scripts Overview

setup.sh

  • Interactive version selection (v13, v14, v15, develop)
    • Uses fixed Python/Node versions per Frappe version:
      • v13 → Python 3.9.17, Node 14
      • v14 → Python 3.10.13, Node 16
      • v15/develop → Python 3.11, Node 18

setup_frappe16.sh

  • Strictly for Frappe v16 with the latest stable toolchain:
    • Python 3.14.0
    • Node 24
    • Yarn 1.22.22
  • Suitable for new projects targeting v16.

Both scripts automatically:

  • Set socketio port to webport + 1000
  • Remove Redis and socketio entries from Procfile (since socketio is integrated with the web process in v16)
  • Configure MariaDB and Redis hosts via bench set-config

:memo: Important Notes

  • Ports – you choose the web port; the socketio port will be webport + 1000. Make sure these are free on your host.
  • Multiple projects – each project uses its own Docker Compose project name (derived from your project name) so there are no collisions.
  • Data persistence – MariaDB data is stored in a named volume (e.g., myapp_mariadb_data), so your data survives container restarts.
  • Administrator password – default is admin. You can change it via bench --site yoursite set-admin-password.
  • **ERPNext – **if you choose to install it, the script will fetch the same branch as Frappe and install it automatically.

:spouting_whale: Docker Details

The generated environment includes four containers:

Container	  -> Purpose
mariadb	    -> MariaDB 11.8 database
redis-cache	-> Redis for caching
redis-queue	-> Redis for background jobs and SocketIO

frappe The main container with bench, Python, Node, and your code
The frappe container uses the official frappe/bench:latest image and runs sleep infinity to stay alive; you start the bench via ./start.sh.

:handshake: Contributing
Found a bug or have a suggestion? Feel free to open an issue or submit a pull request. All contributions are welcome!

:page_facing_up: License
This project is licensed under the MIT License – see the LICENSE file for details.

:speech_balloon: Need Help?
Check the generated PROJECT_INFO.md inside your project folder.

Open the container console with ./console.sh and run bench --help.

Refer to the Frappe Framework Documentation.

Happy coding! :tada:

2 Likes
2

Hi @pra17shant

Looks interesting

I normally have issues with these 4 bench commands in the normal Official Frappe Docker script - build, get-app, update & new-app. Thats why I use Frappe-Manager

  1. Does you script solve this problem?
  2. Also which directories are you binding or mounting to the volume?

Thanks

3

Running your own Frappe/ERPNext environment is as simple as executing a single command.

Ensure you have Docker or Podman installed, then run:

docker run -d \ --name my-frappe-instance \ -p 8080:8000 \ docker.io/vyogo/erpnext:sne-version-16

OR

docker run -d \ --name my-frappe-instance \ -p 8080:8000 \ docker.io/vyogo/erpnext:sne-version-develop

Accessing the application:

  1. Wait a moment for the internal services (MariaDB, Redis, etc.) to start.
  2. Open your browser and navigate to: http://localhost:8080
  3. Login using the default credentials:
  • Username: Administrator
  • Password: admin (or ChangeMe depending on the build configuration)

Frappista provides more simpler and instant environments for devs.

4

The scripts are designed to be project‑isolated – each project gets its own set of containers, ports, and volumes, so you can run multiple projects simultaneously without conflicts. The start.sh , stop.sh , etc. scripts make daily work convenient.

1. Does the script solve the issues with build , get‑app , update , and new‑app ?

The primary cause of problems with those commands in the official Frappe Docker setup is environment mismatches – incorrect Python, Node, or Yarn versions, or missing system dependencies.

My scripts explicitly enforce specific, stable versions:

  • setup_frappe16.sh (for Frappe v16) uses Python 3.14.0 , Node 24 , and Yarn 1.22.22 , all installed via pyenv and nvm inside the container. They are also symlinked to /usr/local/bin so they become the system default for every session.
  • setup.sh (for v13–develop) lets you choose the Frappe branch and automatically sets the matching Python/Node versions (e.g., Python 3.9.17 + Node 14 for v13, etc.).

Because the container’s environment is fixed and reproducible , the commands you mentioned should run without the typical “wrong version” or “missing node” errors. The scripts also:

  • Clean the Procfile (removing Redis entries, as those are separate containers).
  • Configure all Redis and MariaDB hosts correctly.
  • Enable developer mode and clear cache after site creation.

So, yes – this setup eliminates the version‑related pitfalls that often break bench build , get-app , update , and new-app . Of course, if you hit any app‑specific dependency issues, those would still need attention, but the core environment is solid.

2. Which directories are mounted/bound to volumes?

The script mounts only one host directory into the container:

  • Host: ./development (inside your project root)
  • Container: /workspace/development

This is defined in the docker-compose.yml inside .devcontainer :

yaml

volumes: - ./development:/workspace/development

All bench‑related files (the bench folder, sites, apps, etc.) live inside /workspace/development . So after initialization, you’ll have:

text

./development/
└── your-bench-name/ # e.g., euro-bench
├── apps/
├── sites/
├── Procfile
└── …

Additionally , a Docker volume is created for MariaDB data:

yaml

volumes: ${PROJECT_NAME}_mariadb_data:/var/lib/mysql

This ensures your database persists across container restarts.

No other host directories are mounted – everything else stays inside the container or in Docker volumes. This keeps the setup clean and isolated per project.

Cheers,
Pra17shant

1 Like
5

Guys I made something similar. Except that Github - demostackkit also seeds data for different Industries in one command. Idea is you can run multiple sites seeded independent of each other.

1 Like
6

@black_mamba @pra17shant can either solution be used for external access (not from local host) ie: use DNS multi tenant?

7

Nope the intent for creating `demostackkit` is for demo purposed only. Its not intended for production use. Although I need to check if this works with something like Ngrock.

8

While “show & tell” is nice for a basic intro, potential users really need to get real experience using the system on their own to get a feel and generate meaningful questions.

9

What would you suggest?

  1. Create a separate app that seeds data for Production use?
  2. Modify existing implementation to support the DNS use-case?
10

I would be most interested in how you automate the creation of the sample data. Frappe has a basic sample data, but yours seems more comprehensive.

Since I’ve been avoiding Docker all together, generating the sample data in a bare metal/VM install would be great.

11

I’ve update README describing my approach