mirror of
https://github.com/frappe/bench.git
synced 2024-11-11 07:41:03 +00:00
docs: added bench usage docs
This commit is contained in:
Gavin D'souza
parent
c8fa035e4c
commit
9107581a56
249
docs/bench_usage.md
Normal file
249
docs/bench_usage.md
Normal file
@ -0,0 +1,249 @@
|
||||
# bench CLI Usage
|
||||
|
||||
This may not be known to a lot of people but half the bench commands we're used to, exist in the Frappe Framework and not in bench directly. Those commands generally are the `--site` commands. This page is concerned only with the commands in the bench project. Any framework commands won't be a part of this consolidation.
|
||||
|
||||
|
||||
## How are Frappe Framework commands available via bench?
|
||||
|
||||
bench utilizes `frappe.utils.bench_manager` to get the framework's as well as those of any custom commands written in application installed in the Frappe environment. Currently, with *version 12* there are commands related to the scheduler, sites, translations and other utils in Frappe inherited by bench.
|
||||
|
||||
|
||||
## Can I add CLI commands in my custom app and call them via bench?
|
||||
|
||||
Along with the framework commands, Frappe's `bench_manager` module also searches for any commands in your custom applications. Thereby, bench communicates with the respective bench's Frappe which in turn checks for available commands in all of the applications.
|
||||
|
||||
To make your custom command available to bench, just create a `commands` module under your parent module and write the command with a click wrapper and a variable commands which contains a list of click functions, which are your own commands. The directory strcuture may be visualized as:
|
||||
|
||||
```
|
||||
frappe-bench
|
||||
|──apps
|
||||
|── frappe
|
||||
├── custom_app
|
||||
│ ├── README.md
|
||||
│ ├── custom_app
|
||||
│ │ ├── commands <------ commands module
|
||||
│ ├── license.txt
|
||||
│ ├── requirements.txt
|
||||
│ └── setup.py
|
||||
```
|
||||
|
||||
The commands module maybe a single file such as `commands.py` or a directory with an `__init__.py` file. For a custom application of name 'flags', example may be given as
|
||||
|
||||
```python
|
||||
# file_path: frappe-bench/apps/flags/flags/commands.py
|
||||
import click
|
||||
|
||||
@click.command('set-flags')
|
||||
@click.argument('state', type=click.Choice(['on', 'off']))
|
||||
def set_flags(state):
|
||||
from flags.utils import set_flags
|
||||
set_flags(state=state)
|
||||
|
||||
commands = [
|
||||
set_flags
|
||||
]
|
||||
```
|
||||
|
||||
and with context of the current bench, this command maybe executed simply as
|
||||
|
||||
```zsh
|
||||
➜ bench set-flags
|
||||
Flags are set to state: 'on'
|
||||
```
|
||||
|
||||
# bench CLI Commands
|
||||
|
||||
Under Click's structure, `bench` is the main command group, under which there are three main groups of commands in bench currently, namely
|
||||
|
||||
- **install**: The install command group deals with commands used to install system dependencies for setting up Frappe environment
|
||||
|
||||
- **setup**: This command group for consists of commands used to maipulate the requirements and environments required by your Frappe environment
|
||||
|
||||
- **config**: The config command group deals with making changes in the current bench (not the CLI tool) configuration
|
||||
|
||||
|
||||
## Using the bench command line
|
||||
|
||||
```zsh
|
||||
➜ bench
|
||||
Usage: bench [OPTIONS] COMMAND [ARGS]...
|
||||
|
||||
Bench manager for Frappe
|
||||
|
||||
Options:
|
||||
--version
|
||||
--help Show this message and exit.
|
||||
|
||||
Commands:
|
||||
backup Backup single site
|
||||
backup-all-sites Backup all sites in current bench
|
||||
config Change bench configuration
|
||||
disable-production Disables production environment for the bench.
|
||||
download-translations Download latest translations
|
||||
exclude-app Exclude app from updating
|
||||
find Finds benches recursively from location
|
||||
get-app Clone an app from the internet or filesystem and...
|
||||
```
|
||||
|
||||
Similarly, all available flags and options can be checked for commands individually by executing them with the `--help` flag. The `init` command for instance:
|
||||
|
||||
```zsh
|
||||
➜ bench init --help
|
||||
Usage: bench init [OPTIONS] PATH
|
||||
|
||||
Initialize a new bench instance in the specified path
|
||||
|
||||
Options:
|
||||
--python TEXT Path to Python Executable.
|
||||
--ignore-exist Ignore if Bench instance exists.
|
||||
--apps_path TEXT path to json files with apps to install
|
||||
after init
|
||||
```
|
||||
|
||||
|
||||
|
||||
## bench and sudo
|
||||
|
||||
Some bench commands may require sudo, such as some `setup` commands and everything else under the `install` commands group. For these commands, you may not be asked for your root password if sudoers setup has been done. The security implications, well we'll talk about those soon.
|
||||
|
||||
|
||||
|
||||
## General Commands
|
||||
|
||||
These commands belong directly to the bench group so they can be invoked directly prefixing each with `bench` in your shell. Therefore, the usage for these commands is as
|
||||
|
||||
```zsh
|
||||
bench COMMAND [ARGS]...
|
||||
```
|
||||
|
||||
### The usual commands
|
||||
|
||||
- **init**: Initialize a new bench instance in the specified path
|
||||
- **restart**: Restart supervisor processes or systemd units. Used in production setup
|
||||
- **update**: Updates bench tool and if executed in a bench directory, without any flags will backup, pull, setup requirements, build, run patches and restart bench. Using specific flags will only do certain tasks instead of all
|
||||
- **migrate-env**: Migrate Virtual Environment to desired Python Version
|
||||
- **retry-upgrade**: Retry a failed upgrade
|
||||
- **disable-production**: Disables production environment for the bench.
|
||||
- **renew-lets-encrypt**: Renew Let's Encrypt certificate
|
||||
- **backup**: Backup single site
|
||||
- **backup-all-sites**: Backup all sites in current bench
|
||||
|
||||
- **get-app**: Clone an app from the internet or filesystem and set it up in your bench
|
||||
- **remove-app**: Completely remove app from bench and re-build assets if not installed on any site
|
||||
- **exclude-app**: Exclude app from updating
|
||||
- **include-app**: Include app for updating
|
||||
- **remote-set-url**: Set app remote url
|
||||
- **remote-reset-url**: Reset app remote url to frappe official
|
||||
- **remote-urls**: Show apps remote url
|
||||
- **switch-to-branch**: Switch all apps to specified branch, or specify apps separated by space
|
||||
- **switch-to-develop**: Switch frappe and erpnext to develop branch
|
||||
|
||||
|
||||
### A little advanced
|
||||
|
||||
- **set-nginx-port**: Set NGINX port for site
|
||||
- **set-ssl-certificate**: Set SSL certificate path for site
|
||||
- **set-ssl-key**: Set SSL certificate private key path for site
|
||||
- **set-url-root**: Set URL root for site
|
||||
- **set-mariadb-host**: Set MariaDB host for bench
|
||||
- **set-redis-cache-host**: Set Redis cache host for bench
|
||||
- **set-redis-queue-host**: Set Redis queue host for bench
|
||||
- **set-redis-socketio-host**: Set Redis socketio host for bench
|
||||
- **set-default-site**: Set default site for bench
|
||||
- **download-translations**: Download latest translations
|
||||
|
||||
|
||||
### Developer's commands
|
||||
|
||||
- **start**: Start Frappe development processes
|
||||
- **src**: Prints bench source folder path, which can be used as: cd `bench src`
|
||||
- **find**: Finds benches recursively from location
|
||||
- **pip**: For pip help use `bench pip help [COMMAND]` or `bench pip [COMMAND] -h`
|
||||
- **new-app**: Create a new Frappe application under apps folder
|
||||
|
||||
|
||||
### Release bench
|
||||
- **release**: Release a Frappe application
|
||||
- **prepare-beta-release**: Prepare major beta release from develop branch
|
||||
|
||||
|
||||
|
||||
## Setup commands
|
||||
|
||||
The setup commands used for setting up the Frappe environment in context of the current bench need to be executed using `bench setup` as the prefix. So, the general usage of these commands is as
|
||||
|
||||
```zsh
|
||||
bench setup COMMAND [ARGS]...
|
||||
```
|
||||
|
||||
- **sudoers**: Add commands to sudoers list for execution without password
|
||||
|
||||
- **env**: Setup virtualenv for bench
|
||||
- **redis**: Generates configuration for Redis
|
||||
- **fonts**: Add Frappe fonts to system
|
||||
- **config**: Generate or over-write sites/common_site_config.json
|
||||
- **backups**: Add cronjob for bench backups
|
||||
- **socketio**: Setup node dependencies for socketio server
|
||||
- **requirements**: Setup Python and Node dependencies
|
||||
|
||||
- **manager**: Setup bench-manager.local site with the bench_manager app installed on it
|
||||
|
||||
- **procfile**: Generate Procfile for bench start
|
||||
|
||||
- **production**: Setup Frappe production environment for specific user
|
||||
- **nginx**: Generate configuration files for NGINX
|
||||
- **fail2ban**: Setup fail2ban, an intrusion prevention software framework that protects computer servers from brute-force attacks
|
||||
- **systemd**: Generate configuration for systemd
|
||||
- **firewall**: Setup firewall for system
|
||||
- **ssh-port**: Set SSH Port for system
|
||||
- **reload-nginx**: Checks NGINX config file and reloads service
|
||||
- **supervisor**: Generate configuration for supervisor
|
||||
- **lets-encrypt**: Setup lets-encrypt SSL for site
|
||||
- **wildcard-ssl**: Setup wildcard SSL certificate for multi-tenant bench
|
||||
|
||||
- **add-domain**: Add a custom domain to a particular site
|
||||
- **remove-domain**: Remove custom domain from a site
|
||||
- **sync-domains**: Check if there is a change in domains. If yes, updates the domains list.
|
||||
|
||||
- **role**: Install dependencies via ansible roles
|
||||
|
||||
|
||||
|
||||
## Config commands
|
||||
|
||||
The config group commands are used for manipulating configurations in the current bench context. The usage for these commands is as
|
||||
|
||||
```zsh
|
||||
bench config COMMAND [ARGS]...
|
||||
```
|
||||
|
||||
- **set-common-config**: Set value in common config
|
||||
- **remove-common-config**: Remove specific keys from current bench's common config
|
||||
|
||||
- **update_bench_on_update**: Enable/Disable bench updates on running bench update
|
||||
- **restart_supervisor_on_update**: Enable/Disable auto restart of supervisor processes
|
||||
- **restart_systemd_on_update**: Enable/Disable auto restart of systemd units
|
||||
- **dns_multitenant**: Enable/Disable bench multitenancy on running bench update
|
||||
- **serve_default_site**: Configure nginx to serve the default site on port 80
|
||||
- **http_timeout**: Set HTTP timeout
|
||||
|
||||
|
||||
|
||||
## Install commands
|
||||
|
||||
The install group commands are used for manipulating system level dependencies. The usage for these commands is as
|
||||
|
||||
```zsh
|
||||
bench install COMMAND [ARGS]...
|
||||
```
|
||||
|
||||
- **prerequisites**: Installs pre-requisite libraries, essential tools like b2zip, htop, screen, vim, x11-fonts, python libs, cups and Redis
|
||||
- **nodejs**: Installs Node.js v8
|
||||
- **nginx**: Installs NGINX. If user is specified, sudoers is setup for that user
|
||||
- **packer**: Installs Oracle virtualbox and packer 1.2.1
|
||||
- **psutil**: Installs psutil via pip
|
||||
- **mariadb**: Install and setup MariaDB of specified version and root password
|
||||
- **wkhtmltopdf**: Installs wkhtmltopdf v0.12.3 for linux
|
||||
- **supervisor**: Installs supervisor. If user is specified, sudoers is setup for that user
|
||||
- **fail2ban**: Install fail2ban, an intrusion prevention software framework that protects computer servers from brute-force attacks
|
||||
- **virtualbox**: Installs supervisor
|
||||
Loading…
Reference in New Issue
Block a user