{"id":13551681,"url":"https://github.com/frappe/bench","last_synced_at":"2025-05-14T02:09:23.026Z","repository":{"id":18454289,"uuid":"21648326","full_name":"frappe/bench","owner":"frappe","description":"CLI to manage Multi-tenant deployments for Frappe apps","archived":false,"fork":false,"pushed_at":"2025-05-08T07:51:03.000Z","size":31815,"stargazers_count":1515,"open_issues_count":118,"forks_count":1264,"subscribers_count":116,"default_branch":"develop","last_synced_at":"2025-05-08T08:38:12.976Z","etag":null,"topics":["cli","frappe-bench","frappe-framework","python","setup-bench"],"latest_commit_sha":null,"homepage":"https://frappeframework.com/docs/user/en/bench","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/frappe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-07-09T10:24:30.000Z","updated_at":"2025-05-08T07:51:09.000Z","dependencies_parsed_at":"2023-10-20T19:53:39.011Z","dependency_job_id":"768009c6-0247-4b0f-bc0a-1122dcac54d3","html_url":"https://github.com/frappe/bench","commit_stats":{"total_commits":1694,"total_committers":138,"mean_commits":12.27536231884058,"dds":0.7467532467532467,"last_synced_commit":"fd6dfc3ae77b9df84373b7e7df19e7ca29333506"},"previous_names":[],"tags_count":79,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frappe%2Fbench","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frappe%2Fbench/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frappe%2Fbench/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frappe%2Fbench/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/frappe","download_url":"https://codeload.github.com/frappe/bench/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253613424,"owners_count":21936273,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","frappe-bench","frappe-framework","python","setup-bench"],"created_at":"2024-08-01T12:01:52.165Z","updated_at":"2025-05-14T02:09:18.012Z","avatar_url":"https://github.com/frappe.png","language":"Python","readme":"\u003cdiv align=\"center\"\u003e\n\n![Logo](resources/logo.png)\n\n## Bench\n**CLI to manage Frappe applications**\n\n\n[![Python version](https://img.shields.io/badge/python-%3E=_3.10-green.svg)](https://www.python.org/downloads/)\n[![PyPI Version](https://badge.fury.io/py/frappe-bench.svg)](https://pypi.org/project/frappe-bench)\n![Platform Compatibility](https://img.shields.io/badge/platform-linux%20%7C%20macos-blue)\n\n\u003c/div\u003e\n\n## Bench\n\nBench is a command-line utility that helps you to install, update, and manage multiple sites for Frappe applications on [*nix systems](https://en.wikipedia.org/wiki/Unix-like) for development and production.\n\n## Key features\n\nBench helps you set up and manage your frappe sites with ease. Here are some of the key features:\n- Initializing a new bench to work on sites and apps\n- Creating a new frappe site\n- Creating and installing apps that can be used on the sites\n- Managing frappe sites\n- Managing site backups\n\n## Installation\n\nA typical bench setup provides two types of environments \u0026mdash; Development and Production.\n\nThe setup for each of these installations can be achieved in multiple ways:\n\n - [Containerized Installation](#containerized-installation)\n - [Manual Installation](https://docs.frappe.io/framework/user/en/tutorial/install-and-setup-bench)\n\nWe recommend using Docker Installation to setup a Production Environment. For Development, you may choose either of the two methods to setup an instance.\n\nOtherwise, if you are looking to evaluate Frappe apps without the hassle of managing hosting yourself, you can try them on [Frappe Cloud](https://frappecloud.com/).\n\n\u003cdiv\u003e\n\t\u003ca href=\"https://frappecloud.com/dashboard/signup\" target=\"_blank\"\u003e\n\t\t\u003cpicture\u003e\n\t\t\t\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://frappe.io/files/try-on-fc-white.png\"\u003e\n\t\t\t\u003cimg src=\"https://frappe.io/files/try-on-fc-black.png\" alt=\"Try on Frappe Cloud\" height=\"28\" /\u003e\n\t\t\u003c/picture\u003e\n\t\u003c/a\u003e\n\u003c/div\u003e\n\n### Containerized Installation\n\nA Frappe instance can be setup and replicated easily using [Docker](https://docker.com). The officially supported Docker installation can be used to setup either of both Development and Production environments.\n\nTo setup either of the environments, you will need to clone the official docker repository:\n\n```sh\ngit clone https://github.com/frappe/frappe_docker.git\n```\n\nA quick setup guide for both the environments can be found below. For more details, check out the [Frappe Docker Repository](https://github.com/frappe/frappe_docker).\n\n### Easy Install Script\n\nThe Easy Install script should get you going with a Frappe setup with minimal manual intervention and effort.\n\nThis script uses Docker with the [Frappe Docker Repository](https://github.com/frappe/frappe_docker) and can be used for both Development setup and Production setup.\n\n#### Setup\n\nDownload the Easy Install script and execute it:\n\n```sh\nwget https://raw.githubusercontent.com/frappe/bench/develop/easy-install.py\npython3 easy-install.py deploy --email=user@domain.tld --sitename=subdomain.domain.tld --app=erpnext\n```\n\nThis script will install docker on your system and will fetch the required containers, setup bench and a default ERPNext instance.\n\nThe 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.\nIt will also generate a new compose file under `$HOME/\u003cproject-name\u003e-compose.yml`.\n\nWhen the setup is complete, you will be able to access the system at `http://\u003cyour-server-ip\u003e`, wherein you can use the Administrator password to login.\n\n#### Arguments\n\nHere are the arguments for the easy-install script\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eBuild custom images\u003c/b\u003e\u003c/summary\u003e\n\n```txt\nusage: easy-install.py build [-h] [-n PROJECT] [-i IMAGE] [-q] [-m HTTP_PORT] [-v VERSION] [-a APPS] [-s SITES] [-e EMAIL]\n                             [-p] [-r FRAPPE_PATH] [-b FRAPPE_BRANCH] [-j APPS_JSON] [-t TAGS] [-c CONTAINERFILE]\n                             [-y PYTHON_VERSION] [-d NODE_VERSION] [-x] [-u]\n\noptions:\n  -h, --help            show this help message and exit\n  -n PROJECT, --project PROJECT\n                        Project Name\n  -g, --backup-schedule BACKUP_SCHEDULE\n                        Backup schedule cronstring, default: \"@every 6h\"\n  -i IMAGE, --image IMAGE\n                        Full Image Name\n  -q, --no-ssl          No https\n  -m HTTP_PORT, --http-port HTTP_PORT\n                        Http port in case of no-ssl\n  -v VERSION, --version VERSION\n                        ERPNext version to install, defaults to latest stable\n  -a APPS, --app APPS   list of app(s) to be installed\n  -s SITES, --sitename SITES\n                        Site Name(s) for your production bench\n  -e EMAIL, --email EMAIL\n                        Add email for the SSL.\n  -p, --push            Push the built image to registry\n  -r FRAPPE_PATH, --frappe-path FRAPPE_PATH\n                        Frappe Repository to use, default: https://github.com/frappe/frappe\n  -b FRAPPE_BRANCH, --frappe-branch FRAPPE_BRANCH\n                        Frappe branch to use, default: version-15\n  -j APPS_JSON, --apps-json APPS_JSON\n                        Path to apps json, default: frappe_docker/development/apps-example.json\n  -t TAGS, --tag TAGS   Full Image Name(s), default: custom-apps:latest\n  -c CONTAINERFILE, --containerfile CONTAINERFILE\n                        Path to Containerfile: images/layered/Containerfile\n  -y PYTHON_VERSION, --python-version PYTHON_VERSION\n                        Python Version, default: 3.11.6\n  -d NODE_VERSION, --node-version NODE_VERSION\n                        NodeJS Version, default: 18.18.2\n  -x, --deploy          Deploy after build\n  -u, --upgrade         Upgrade after build\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDeploy using compose\u003c/b\u003e\u003c/summary\u003e\n\n```txt\nusage: easy-install.py deploy [-h] [-n PROJECT] [-i IMAGE] [-q] [-m HTTP_PORT] [-v VERSION] [-a APPS] [-s SITES] [-e EMAIL]\n\noptions:\n  -h, --help            show this help message and exit\n  -n PROJECT, --project PROJECT\n                        Project Name\n  -g, --backup-schedule BACKUP_SCHEDULE\n                        Backup schedule cronstring, default: \"@every 6h\"\n  -i IMAGE, --image IMAGE\n                        Full Image Name\n  -q, --no-ssl          No https\n  -m HTTP_PORT, --http-port HTTP_PORT\n                        Http port in case of no-ssl\n  -v VERSION, --version VERSION\n                        ERPNext version to install, defaults to latest stable\n  -a APPS, --app APPS   list of app(s) to be installed\n  -s SITES, --sitename SITES\n                        Site Name(s) for your production bench\n  -e EMAIL, --email EMAIL\n                        Add email for the SSL.\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eUpgrade existing project\u003c/b\u003e\u003c/summary\u003e\n\n```txt\nusage: easy-install.py upgrade [-h] [-n PROJECT] [-i IMAGE] [-q] [-m HTTP_PORT] [-v VERSION]\n\noptions:\n  -h, --help            show this help message and exit\n  -n PROJECT, --project PROJECT\n                        Project Name\n  -g, --backup-schedule BACKUP_SCHEDULE\n                        Backup schedule cronstring, default: \"@every 6h\"\n  -i IMAGE, --image IMAGE\n                        Full Image Name\n  -q, --no-ssl          No https\n  -m HTTP_PORT, --http-port HTTP_PORT\n                        Http port in case of no-ssl\n  -v VERSION, --version VERSION\n                        ERPNext or image version to install, defaults to latest stable\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDevelopment setup using compose\u003c/b\u003e\u003c/summary\u003e\n\n```txt\nusage: easy-install.py develop [-h] [-n PROJECT]\n\noptions:\n  -h, --help            show this help message and exit\n  -n PROJECT, --project PROJECT\n                        Compose project name\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eExec into existing project\u003c/b\u003e\u003c/summary\u003e\n\n```txt\nusage: easy-install.py exec [-h] [-n PROJECT]\n\noptions:\n  -h, --help            show this help message and exit\n  -n PROJECT, --project PROJECT\n                        Project Name\n```\n\u003c/details\u003e\n\nTo use custom apps, you need to create a json file with list of apps and pass it to build command.\n\nExample apps.json\n\n```json\n[\n  {\n    \"url\": \"https://github.com/frappe/wiki.git\",\n    \"branch\": \"master\"\n  }\n]\n```\n\nExecute following command to build and deploy above apps:\n\n```sh\n$ python3 easy-install.py build \\\n\t--tag=ghcr.io/org/repo/custom-apps:latest \\\n\t--push \\\n\t--image=ghcr.io/org/repo/custom-apps \\\n\t--version=latest \\\n\t--deploy \\\n\t--project=actions_test \\\n\t--email=test@frappe.io \\\n\t--apps-json=apps.json \\\n\t--app=wiki\n```\n\nNote:\n\n- `--tag`, tag to set for built image, can be multiple.\n- `--push`, push the built image.\n- `--image`, the image to use when starting docker compose project.\n- `--version`, the version to use when starting docker compose project.\n- `--app`, app to install on site creation, can be multiple.\n- `--deploy`, flag to deploy after build/push is complete\n- `--project=actions_test`, name of the project, compose file with project name will be stored in user home directory.\n- `--email=test@frappe.io`, valid email for letsencrypt certificate expiry notification.\n- `--apps-json`, path to json file with list of apps to be added to bench.\n\n#### Troubleshooting\n\nIn case the setup fails, the log file is saved under `$HOME/easy-install.log`. You may then\n\n- Create an Issue in this repository with the log file attached.\n\n## Basic Usage\n\n**Note:** Apart from `bench init`, all other bench commands are expected to be run in the respective bench directory.\n\n * Create a new bench:\n\n\t```sh\n\t$ bench init [bench-name]\n\t```\n\n * Add a site under current bench:\n\n\t```sh\n\t$ bench new-site [site-name]\n\t```\n\t- **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.\n\n\t\t```sh\n\t\t$ bench new-site [site-name] --db-host [custom-db-host-ip] --db-port [custom-db-port]\n\t\t```\n\n * Download and add applications to bench:\n\n\t```sh\n\t$ bench get-app [app-name] [app-link]\n\t```\n\n * Install apps on a particular site\n\n\t```sh\n\t$ bench --site [site-name] install-app [app-name]\n\t```\n\n * Start bench (only for development)\n\n\t```sh\n\t$ bench start\n\t```\n\n * Show bench help:\n\n\t```sh\n\t$ bench --help\n\t```\n\n\nFor more in-depth information on commands and their usage, follow [Commands and Usage](https://github.com/frappe/bench/blob/develop/docs/commands_and_usage.md). As for a consolidated list of bench commands, check out [Bench Usage](https://github.com/frappe/bench/blob/develop/docs/bench_usage.md).\n\n![Help](resources/help.png)\n\n\n## Custom Bench Commands\n\nIf you wish to extend the capabilities of bench with your own custom Frappe Application, you may follow [Adding Custom Bench Commands](https://github.com/frappe/bench/blob/develop/docs/bench_custom_cmd.md).\n\n\n## Guides\n\n- [Configuring HTTPS](https://docs.frappe.io/framework/user/en/bench/guides/configuring-https)\n- [Using Let's Encrypt to setup HTTPS](https://docs.frappe.io/framework/user/en/bench/guides/lets-encrypt-ssl-setup)\n- [Diagnosing the Scheduler](https://docs.frappe.io/framework/user/en/bench/guides/diagnosing-the-scheduler)\n- [Change Hostname](https://docs.frappe.io/framework/user/en/bench/guides/adding-custom-domains)\n- [Manual Setup](https://docs.frappe.io/framework/user/en/tutorial/install-and-setup-bench)\n- [Setup Production](https://docs.frappe.io/framework/user/en/bench/guides/setup-production)\n- [Setup Multitenancy](https://docs.frappe.io/framework/user/en/bench/guides/setup-multitenancy)\n- [Stopping Production](https://github.com/frappe/bench/wiki/Stopping-Production-and-starting-Development)\n\n\n## Resources\n\n- [Bench Commands Cheat Sheet](https://docs.frappe.io/framework/user/en/bench/resources/bench-commands-cheatsheet)\n- [Background Services](https://docs.frappe.io/framework/user/en/bench/resources/background-services)\n- [Bench Procfile](https://docs.frappe.io/framework/user/en/bench/resources/bench-procfile)\n\n\n## Development\n\nTo 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:\n\n\tWARN: bench is installed in editable mode!\n\n\tThis is not the recommended mode of installation for production. Instead, install the package from PyPI with: `pip install frappe-bench`\n\n### Clone and install\n\n```sh\ngit clone https://github.com/frappe/bench ~/bench-repo\npip install -e ~/bench-repo\n```\n\n```shell\nbench src\n```\nThis should display $HOME/bench-repo\n\n### To clear up the editable install and delete the corresponding egg file from the python path:\n\n```sh\n# Delete bench installed in editable install\npip uninstall frappe-bench\n```\n\n### Then you can install the latest from PyPI\n```sh\npip install -U frappe-bench\n```\n\nTo confirm the switch, check the output of `bench src`. It should change from something like `$HOME/bench-repo` to `/usr/local/lib/python3.12/dist-packages` and stop the editable install warnings from getting triggered at every command.\n\n\n## Releases\n\nBench's version information can be accessed via `bench.VERSION` in the package's __init__.py file. Ever since the v5.0 release, we've started publishing releases on GitHub, and PyPI.\n\n[GitHub](https://github.com/frappe/bench/releases)\n[Pypi](https://pypi.org/project/frappe-bench)\n\n\n## Learn and connect\n\n- [Discuss](https://discuss.frappe.io/)\n- [YouTube](https://www.youtube.com/@frappetech)\n\n## Contribute\nTo contribute to this project, please review the [Contribution Guidelines](https://github.com/frappe/erpnext/wiki/Contribution-Guidelines) for detailed instructions. Make sure to follow our [Code of Conduct](https://github.com/frappe/frappe/blob/develop/CODE_OF_CONDUCT.md) to keep the community welcoming and respectful.\n\n## Security\nThe Frappe team and community prioritize security. If you discover a security issue, please report it via our [Security Report Form](https://frappe.io/security).\nYour responsible disclosure helps keep Frappe and its users safe. We'll do our best to respond quickly and keep you informed throughout the process.\nFor guidelines on reporting, check out our [Reporting Guidelines](https://frappe.io/security), and review our [Logo and Trademark Policy](https://github.com/frappe/erpnext/blob/develop/TRADEMARK_POLICY.md) for branding information.\n\n\u003cbr/\u003e\u003cbr/\u003e\n\u003cdiv align=\"center\"\u003e\n\t\u003ca href=\"https://frappe.io\" target=\"_blank\"\u003e\n\t\t\u003cpicture\u003e\n\t\t\t\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://frappe.io/files/Frappe-white.png\"\u003e\n\t\t\t\u003cimg src=\"https://frappe.io/files/Frappe-black.png\" alt=\"Frappe Technologies\" height=\"28\"/\u003e\n\t\t\u003c/picture\u003e\n\t\u003c/a\u003e\n\u003c/div\u003e\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrappe%2Fbench","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrappe%2Fbench","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrappe%2Fbench/lists"}