Bench is a command-line utility that helps you to install, update, and manage multiple sites for Frappe/ERPNext applications on *nix systems for development and production.
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 hassle of hosting, you can try them on frappecloud.com.
A Frappe/ERPNext 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
$ cd frappe_docker
A quick setup guide for both the environments can be found below. For more details, check out the Frappe/ERPNext Docker Repository.
The Easy Install script should get you going with a Frappe/ERPNext setup with minimal manual intervention and effort.
This script uses Docker with the Frappe/ERPNext Docker Repository and can be used for both Development setup and Production setup.
Download the Easy Install script and execute it:
$ wget https://raw.githubusercontent.com/frappe/bench/develop/easy-install.py
$ python3 easy-install.py --prod --email your@email.tld
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.
Here are the arguments for the easy-install script
usage: easy-install.py [-h] [-p] [-d] [-s SITENAME] [-n PROJECT] [--email EMAIL]
Install Frappe with Docker
options:
-h, --help show this help message and exit
-p, --prod Setup Production System
-d, --dev Setup Development System
-s SITENAME, --sitename SITENAME The Site Name for your production site
-n PROJECT, --project PROJECT Project Name
--email EMAIL Add email for the SSL.
In case the setup fails, the log file is saved under $HOME/easy-install.log. You may then
Some might want to manually setup a bench instance locally for development. To quickly get started on installing bench the hard way, you can follow the guide on Installing Bench and the Frappe Framework.
You'll have to set up the system dependencies required for setting up a Frappe Environment. Checkout docs/installation for more information on this. If you've already set up, install bench via pip:
$ pip install frappe-bench
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-name] --db-host [custom-db-host-ip] --db-port [custom-db-port]
Download and add applications to bench:
$ bench get-app [app-name] [app-link]
Install apps on a particular site
$ bench --site [site-name] install-app [app-name]
Start bench (only for development)
$ bench start
Show bench help:
$ bench --help
For more in-depth information on commands and their usage, follow Commands and Usage. As for a consolidated list of bench commands, check out Bench Usage.
If you wish to extend the capabilities of bench with your own custom Frappe Application, you may follow Adding Custom Bench Commands.
For an exhaustive list of guides, check out Bench Guides.
For an exhaustive list of resources, check out Bench Resources.
To contribute and develop on the bench CLI tool, clone this repo and create an editable install. In editable mode, you may get the following warning everytime you run a bench command:
WARN: bench is installed in editable mode!
This is not the recommended mode of installation for production. Instead, install the package from PyPI with: `pip install frappe-bench`
$ git clone https://github.com/frappe/bench ~/bench-repo
$ pip3 install -e ~/bench-repo
$ bench src
/Users/frappe/bench-repo
To clear up the editable install and switch to a stable version of bench, uninstall via pip and delete the corresponding egg file from the python path.
# Delete bench installed in editable install
$ rm -r $(find ~ -name '*.egg-info')
$ pip3 uninstall frappe-bench
# Install latest released version of bench
$ pip3 install -U frappe-bench
To confirm the switch, check the output of bench src. It should change from something like $HOME/bench-repo to /usr/local/lib/python3.6/dist-packages and stop the editable install warnings from getting triggered at every command.
Bench's version information can be accessed via bench.VERSION in the package's init.py file. Eversince the v5.0 release, we've started publishing releases on GitHub, and PyPI.
GitHub: https://github.com/frappe/bench/releases
PyPI: https://pypi.org/project/frappe-bench
From v5.3.0, we partially automated the release process using @semantic-release. Under this new pipeline, we do the following steps to make a release:
develop into the staging branchstaging into the latest stable branch, which is v5.x at this point.This triggers a GitHub Action job that generates a bump commit, drafts and generates a GitHub release, builds a Python package and publishes it to PyPI.
The intermediate staging branch exists to mediate the bench.VERSION conflict that would arise while merging develop and stable. On develop, the version has to be manually updated (for major release changes). The version tag plays a role in deciding when checks have to be made for new Bench releases.
Note: We may want to kill the convention of separate branches for different version releases of Bench. We don't need to maintain this the way we do for Frappe & ERPNext. A single branch named
stablewould sustain.
This repository has been released under the GNU GPLv3 License.
FAQs
CLI to manage Multi-tenant deployments for Frappe apps
We found that frappe-bench demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.