accounting/bench
2
0
Fork 0
mirror of https://github.com/frappe/bench.git synced 2025-01-02 22:00:17 +00:00
Code Issues Releases Activity

refactor: README

Browse Source 
Signed-off-by: Akhil Narang <me@akhilnarang.dev>
This commit is contained in:
Akhil Narang 2024-12-18 16:55:11 +05:30
parent 6d2ce9691f
commit 9f76d3a398
No known key found for this signature in database
GPG Key ID: 9DCC61E211BF645F
3 changed files with 101 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

210
README.md
View File

@ -1,52 +1,29 @@
<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/frappe/design/raw/master/logos/png/bench-logo-dark.png">
<img src="https://github.com/frappe/design/raw/master/logos/png/bench-logo.png" height="128">
</picture>
<h2>Bench</h2>
![Logo](resources/logo.png)
## Bench
**CLI to manage Frappe applications**
[![Python version](https://img.shields.io/badge/python-%3E=_3.10-green.svg)](https://www.python.org/downloads/)
[![PyPI Version](https://badge.fury.io/py/frappe-bench.svg)](https://pypi.org/project/frappe-bench)
![Platform Compatibility](https://img.shields.io/badge/platform-linux%20%7C%20macos-blue)
</div>
Bench is a command-line utility that helps you to install, update, and manage multiple sites for Frappe/ERPNext applications on [*nix systems](https://en.wikipedia.org/wiki/Unix-like) for development and production.
## Bench
<div align="center">
<a target="_blank" href="https://www.python.org/downloads/" title="Python version">
<img src="https://img.shields.io/badge/python-%3E=_3.8-green.svg">
</a>
<a target="_blank" href="https://app.travis-ci.com/github/frappe/bench" title="CI Status">
<img src="https://app.travis-ci.com/frappe/bench.svg?branch=develop">
</a>
<a target="_blank" href="https://pypi.org/project/frappe-bench" title="PyPI Version">
<img src="https://badge.fury.io/py/frappe-bench.svg" alt="PyPI version">
</a>
<a target="_blank" title="Platform Compatibility">
<img src="https://img.shields.io/badge/platform-linux%20%7C%20osx-blue">
</a>
<a target="_blank" href="https://app.fossa.com/projects/git%2Bgithub.com%2Ffrappe%2Fbench?ref=badge_shield" title="FOSSA Status">
<img src="https://app.fossa.com/api/projects/git%2Bgithub.com%2Ffrappe%2Fbench.svg?type=shield">
</a>
<a target="_blank" href="#LICENSE" title="License: GPLv3">
<img src="https://img.shields.io/badge/License-GPLv3-blue.svg">
</a>
</div>
Bench 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.
## Table of Contents
- [Table of Contents](#table-of-contents)
- [Installation](#installation)
- [Containerized Installation](#containerized-installation)
- [Easy Install Script](#easy-install-script)
- [Setup](#setup)
- [Arguments](#arguments)
- [Troubleshooting](#troubleshooting)
- [Manual Installation](#manual-installation)
- [Basic Usage](#basic-usage)
- [Custom Bench Commands](#custom-bench-commands)
- [Guides](#guides)
- [Resources](#resources)
- [Development](#development)
- [Releases](#releases)
- [License](#license)
## 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
@ -55,39 +32,46 @@ A typical bench setup provides two types of environments &mdash; Development and
The setup for each of these installations can be achieved in multiple ways:
- [Containerized Installation](#containerized-installation)
- [Manual Installation](#manual-installation)
- [Manual Installation](https://docs.frappe.io/framework/user/en/tutorial/install-and-setup-bench)
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](https://frappecloud.com/).
Otherwise, 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/).
<div>
<a href="https://frappecloud.com/dashboard/signup" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://frappe.io/files/try-on-fc-white.png">
<img src="https://frappe.io/files/try-on-fc-black.png" alt="Try on Frappe Cloud" height="28" />
</picture>
</a>
</div>
### Containerized Installation
A Frappe/ERPNext 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.
A 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.
To setup either of the environments, you will need to clone the official docker repository:
```sh
$ git clone https://github.com/frappe/frappe_docker.git
$ cd frappe_docker
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/ERPNext Docker Repository](https://github.com/frappe/frappe_docker).
A 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).
### Easy Install Script
The Easy Install script should get you going with a Frappe/ERPNext setup with minimal manual intervention and effort.
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/ERPNext Docker Repository](https://github.com/frappe/frappe_docker) and can be used for both Development setup and Production setup.
This 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.
#### Setup
Download the Easy Install script and execute it:
```sh
$ 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
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.
@ -101,7 +85,8 @@ When the setup is complete, you will be able to access the system at `http://<yo
Here are the arguments for the easy-install script
**Build custom images**
<details>
<summary><b>Build custom images</b></summary>
```txt
usage: easy-install.py build [-h] [-n PROJECT] [-i IMAGE] [-q] [-m HTTP_PORT] [-v VERSION] [-a APPS] [-s SITES] [-e EMAIL]
@ -141,8 +126,10 @@ options:
-x, --deploy Deploy after build
-u, --upgrade Upgrade after build
```
</details>
**Deploy using compose**
<details>
<summary><b>Deploy using compose</b></summary>
```txt
usage: easy-install.py deploy [-h] [-n PROJECT] [-i IMAGE] [-q] [-m HTTP_PORT] [-v VERSION] [-a APPS] [-s SITES] [-e EMAIL]
@ -164,8 +151,10 @@ options:
-e EMAIL, --email EMAIL
Add email for the SSL.
```
</details>
**Upgrade existing project**
<details>
<summary><b>Upgrade existing project</b></summary>
```txt
usage: easy-install.py upgrade [-h] [-n PROJECT] [-i IMAGE] [-q] [-m HTTP_PORT] [-v VERSION]
@ -182,8 +171,10 @@ options:
-v VERSION, --version VERSION
ERPNext or image version to install, defaults to latest stable
```
</details>
**Development setup using compose**
<details>
<summary><b>Development setup using compose</b></summary>
```txt
usage: easy-install.py develop [-h] [-n PROJECT]
@ -193,8 +184,10 @@ options:
-n PROJECT, --project PROJECT
Compose project name
```
</details>
**Exec into existing project**
<details>
<summary><b>Exec into existing project</b></summary>
```txt
usage: easy-install.py exec [-h] [-n PROJECT]
@ -204,6 +197,7 @@ options:
-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.
@ -251,18 +245,6 @@ In case the setup fails, the log file is saved under `$HOME/easy-install.log`. Y
- Create an Issue in this repository with the log file attached.
### Manual Installation
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](https://frappe.io/docs/user/en/installation).
You'll have to set up the system dependencies required for setting up a Frappe Environment. Checkout [docs/installation](https://github.com/frappe/bench/blob/develop/docs/installation.md) for more information on this. If you've already set up, install bench via pip:
```sh
$ pip install frappe-bench
```
## Basic Usage
**Note:** Apart from `bench init`, all other bench commands are expected to be run in the respective bench directory.
@ -311,6 +293,8 @@ $ pip install frappe-bench
For 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).
![Help](resources/help.png)
## Custom Bench Commands
@ -319,25 +303,21 @@ If you wish to extend the capabilities of bench with your own custom Frappe Appl
## Guides
- [Configuring HTTPS](https://frappe.io/docs/user/en/bench/guides/configuring-https.html)
- [Using Let's Encrypt to setup HTTPS](https://frappe.io/docs/user/en/bench/guides/lets-encrypt-ssl-setup.html)
- [Diagnosing the Scheduler](https://frappe.io/docs/user/en/bench/guides/diagnosing-the-scheduler.html)
- [Change Hostname](https://frappe.io/docs/user/en/bench/guides/adding-custom-domains)
- [Manual Setup](https://frappe.io/docs/user/en/bench/guides/manual-setup.html)
- [Setup Production](https://frappe.io/docs/user/en/bench/guides/setup-production.html)
- [Setup Multitenancy](https://frappe.io/docs/user/en/bench/guides/setup-multitenancy.html)
- [Configuring HTTPS](https://docs.frappe.io/framework/user/en/bench/guides/configuring-https)
- [Using Let's Encrypt to setup HTTPS](https://docs.frappe.io/framework/user/en/bench/guides/lets-encrypt-ssl-setup)
- [Diagnosing the Scheduler](https://docs.frappe.io/framework/user/en/bench/guides/diagnosing-the-scheduler)
- [Change Hostname](https://docs.frappe.io/framework/user/en/bench/guides/adding-custom-domains)
- [Manual Setup](https://docs.frappe.io/framework/user/en/tutorial/install-and-setup-bench)
- [Setup Production](https://docs.frappe.io/framework/user/en/bench/guides/setup-production)
- [Setup Multitenancy](https://docs.frappe.io/framework/user/en/bench/guides/setup-multitenancy)
- [Stopping Production](https://github.com/frappe/bench/wiki/Stopping-Production-and-starting-Development)
For an exhaustive list of guides, check out [Bench Guides](https://frappe.io/docs/user/en/bench/guides).
## Resources
- [Bench Commands Cheat Sheet](https://frappe.io/docs/user/en/bench/resources/bench-commands-cheatsheet.html)
- [Background Services](https://frappe.io/docs/user/en/bench/resources/background-services.html)
- [Bench Procfile](https://frappe.io/docs/user/en/bench/resources/bench-procfile.html)
For an exhaustive list of resources, check out [Bench Resources](https://frappe.io/docs/user/en/bench/resources).
- [Bench Commands Cheat Sheet](https://docs.frappe.io/framework/user/en/bench/resources/bench-commands-cheatsheet)
- [Background Services](https://docs.frappe.io/framework/user/en/bench/resources/background-services)
- [Bench Procfile](https://docs.frappe.io/framework/user/en/bench/resources/bench-procfile)
## Development
@ -348,49 +328,61 @@ To contribute and develop on the bench CLI tool, clone this repo and create an e
This is not the recommended mode of installation for production. Instead, install the package from PyPI with: `pip install frappe-bench`
### Clone and install
```sh
$ git clone https://github.com/frappe/bench ~/bench-repo
$ pip3 install -e ~/bench-repo
$ bench src
/Users/frappe/bench-repo
git clone https://github.com/frappe/bench ~/bench-repo
pip install -e ~/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.
```shell
bench src
```
This should display $HOME/bench-repo
### To clear up the editable install and delete the corresponding egg file from the python path:
```sh
# 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
rm -r $(find ~ -name '*.egg-info')
pip uninstall 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.
### Then you can install the latest from PyPI
```sh
pip 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.12/dist-packages` and stop the editable install warnings from getting triggered at every command.
## Releases
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.
Bench'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.
GitHub: https://github.com/frappe/bench/releases
PyPI: https://pypi.org/project/frappe-bench
[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](.github/workflows/release.yml). Under this new pipeline, we do the following steps to make a release:
## Learn and connect
1. Merge `develop` into the `staging` branch
1. Merge `staging` into the latest stable branch, which is `v5.x` at this point.
- [Discuss](https://discuss.frappe.io/)
- [YouTube](https://www.youtube.com/@frappetech)
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.
## Contribute
To 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.
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.
## Security
The Frappe team and community prioritize security. If you discover a security issue, please report it via our [Security Report Form](https://frappe.io/security).
Your responsible disclosure helps keep Frappe and its users safe. We'll do our best to respond quickly and keep you informed throughout the process.
For 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.
> 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 `stable` would sustain.
## License
This repository has been released under the [GNU GPLv3 License](LICENSE).
<br/><br/>
<div align="center">
<a href="https://frappe.io" target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://frappe.io/files/Frappe-white.png">
<img src="https://frappe.io/files/Frappe-black.png" alt="Frappe Technologies" height="28"/>
</picture>
</a>
</div>

BIN
resources/help.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 113 KiB

BIN
resources/logo.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.7 KiB