Bench

CLI to manage Frappe applications

</div>

Bench

Bench is a command-line utility that helps you to install, update, and manage multiple sites for Frappe applications on *nix systems for development and production.

Key features

Bench helps you set up and manage your frappe sites with ease. Here are some of the key features:

Initializing a new bench to work on sites and apps
Creating a new frappe site
Creating and installing apps that can be used on the sites
Managing frappe sites
Managing site backups

Installation

A typical bench setup provides two types of environments — Development and Production.

The setup for each of these installations can be achieved in multiple ways:

We recommend using Docker Installation to setup a Production Environment. For Development, you may choose either of the two methods to setup an instance.

Otherwise, if you are looking to evaluate Frappe apps without the hassle of managing hosting yourself, you can try them on Frappe Cloud.

Containerized Installation

A Frappe instance can be setup and replicated easily using Docker. The officially supported Docker installation can be used to setup either of both Development and Production environments.

To setup either of the environments, you will need to clone the official docker repository:

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

A quick setup guide for both the environments can be found below. For more details, check out the Frappe Docker Repository.

Easy Install Script

The Easy Install script should get you going with a Frappe setup with minimal manual intervention and effort.

This script uses Docker with the Frappe Docker Repository and can be used for both Development setup and Production setup.

Setup

Download the Easy Install script and execute it:

wget https://raw.githubusercontent.com/frappe/bench/develop/easy-install.py
python3 easy-install.py deploy --email=user@domain.tld --sitename=subdomain.domain.tld --app=erpnext

This script will install docker on your system and will fetch the required containers, setup bench and a default ERPNext instance.

The script will generate MySQL root password and an Administrator password for the Frappe/ERPNext instance, which will then be saved under $HOME/passwords.txt of the user used to setup the instance. It will also generate a new compose file under $HOME/<project-name>-compose.yml.

When the setup is complete, you will be able to access the system at http://<your-server-ip>, wherein you can use the Administrator password to login.

Arguments

Here are the arguments for the easy-install script

<details> <summary><b>Build custom images</b></summary>

usage: easy-install.py build [-h] [-n PROJECT] [-i IMAGE] [-q] [-m HTTP_PORT] [-v VERSION] [-a APPS] [-s SITES] [-e EMAIL]
                             [-p] [-r FRAPPE_PATH] [-b FRAPPE_BRANCH] [-j APPS_JSON] [-t TAGS] [-c CONTAINERFILE]
                             [-y PYTHON_VERSION] [-d NODE_VERSION] [-x] [-u]

options:
  -h, --help            show this help message and exit
  -n PROJECT, --project PROJECT
                        Project Name
  -g, --backup-schedule BACKUP_SCHEDULE
                        Backup schedule cronstring, default: "@every 6h"
  -i IMAGE, --image IMAGE
                        Full Image Name
  -q, --no-ssl          No https
  -m HTTP_PORT, --http-port HTTP_PORT
                        Http port in case of no-ssl
  -v VERSION, --version VERSION
                        ERPNext version to install, defaults to latest stable
  -a APPS, --app APPS   list of app(s) to be installed
  -s SITES, --sitename SITES
                        Site Name(s) for your production bench
  -e EMAIL, --email EMAIL
                        Add email for the SSL.
  -p, --push            Push the built image to registry
  -r FRAPPE_PATH, --frappe-path FRAPPE_PATH
                        Frappe Repository to use, default: https://github.com/frappe/frappe
  -b FRAPPE_BRANCH, --frappe-branch FRAPPE_BRANCH
                        Frappe branch to use, default: version-15
  -j APPS_JSON, --apps-json APPS_JSON
                        Path to apps json, default: frappe_docker/development/apps-example.json
  -t TAGS, --tag TAGS   Full Image Name(s), default: custom-apps:latest
  -c CONTAINERFILE, --containerfile CONTAINERFILE
                        Path to Containerfile: images/layered/Containerfile
  -y PYTHON_VERSION, --python-version PYTHON_VERSION
                        Python Version, default: 3.11.6
  -d NODE_VERSION, --node-version NODE_VERSION
                        NodeJS Version, default: 18.18.2
  -x, --deploy          Deploy after build
  -u, --upgrade         Upgrade after build

</details> <details> <summary><b>Deploy using compose</b></summary>

usage: easy-install.py deploy [-h] [-n PROJECT] [-i IMAGE] [-q] [-m HTTP_PORT] [-v VERSION] [-a APPS] [-s SITES] [-e EMAIL]

options:
  -h, --help            show this help message and exit
  -n PROJECT, --project PROJECT
                        Project Name
  -g, --backup-schedule BACKUP_SCHEDULE
                        Backup schedule cronstring, default: "@every 6h"
  -i IMAGE, --image IMAGE
                        Full Image Name
  -q, --no-ssl          No https
  -m HTTP_PORT, --http-port HTTP_PORT
                        Http port in case of no-ssl
  -v VERSION, --version VERSION
                        ERPNext version to install, defaults to latest stable
  -a APPS, --app APPS   list of app(s) to be installed
  -s SITES, --sitename SITES
                        Site Name(s) for your production bench
  -e EMAIL, --email EMAIL
                        Add email for the SSL.

</details> <details> <summary><b>Upgrade existing project</b></summary>

usage: easy-install.py upgrade [-h] [-n PROJECT] [-i IMAGE] [-q] [-m HTTP_PORT] [-v VERSION]

options:
  -h, --help            show this help message and exit
  -n PROJECT, --project PROJECT
                        Project Name
  -g, --backup-schedule BACKUP_SCHEDULE
                        Backup schedule cronstring, default: "@every 6h"
  -i IMAGE, --image IMAGE
                        Full Image Name
  -q, --no-ssl          No https
  -m HTTP_PORT, --http-port HTTP_PORT
                        Http port in case of no-ssl
  -v VERSION, --version VERSION
                        ERPNext or image version to install, defaults to latest stable

</details> <details> <summary><b>Development setup using compose</b></summary>

usage: easy-install.py develop [-h] [-n PROJECT]

options:
  -h, --help            show this help message and exit
  -n PROJECT, --project PROJECT
                        Compose project name

</details> <details> <summary><b>Exec into existing project</b></summary>

usage: easy-install.py exec [-h] [-n PROJECT]

options:
  -h, --help            show this help message and exit
  -n PROJECT, --project PROJECT
                        Project Name

</details>

To use custom apps, you need to create a json file with list of apps and pass it to build command.

Example apps.json

[
  {
    "url": "https://github.com/frappe/wiki.git",
    "branch": "master"
  }
]

Execute following command to build and deploy above apps:

$ python3 easy-install.py build \
	--tag=ghcr.io/org/repo/custom-apps:latest \
	--push \
	--image=ghcr.io/org/repo/custom-apps \
	--version=latest \
	--deploy \
	--project=actions_test \
	--email=test@frappe.io \
	--apps-json=apps.json \
	--app=wiki

Note:

--tag, tag to set for built image, can be multiple.
--push, push the built image.
--image, the image to use when starting docker compose project.
--version, the version to use when starting docker compose project.
--app, app to install on site creation, can be multiple.
--deploy, flag to deploy after build/push is complete
--project=actions_test, name of the project, compose file with project name will be stored in user home directory.
--email=test@frappe.io, valid email for letsencrypt certificate expiry notification.
--apps-json, path to json file with list of apps to be added to bench.

Troubleshooting

In case the setup fails, the log file is saved under $HOME/easy-install.log. You may then

Create an Issue in this repository with the log file attached.

Basic Usage

Note: Apart from bench init, all other bench commands are expected to be run in the respective bench directory.

Create a new bench:
```
$ bench init [bench-name]
```
Add a site under current bench:
```
$ bench new-site [site-name]
```
- Optional: If the database for the site does not reside on localhost or listens on a custom port, you can use the flags --db-host to set a custom host and/or --db-port to set a custom port.
```
$ bench new-site [site
```

Bench

Install / Use

README

Bench

Bench

Key features

Installation

Containerized Installation

Easy Install Script

Setup

Arguments

Troubleshooting

Basic Usage