mirror of
https://github.com/frappe/bench.git
synced 2024-11-14 09:14:04 +00:00
194 lines
5.4 KiB
Markdown
194 lines
5.4 KiB
Markdown
Bench
|
|
=====
|
|
|
|
The bench allows you to setup Frappe apps on your local machine or a production
|
|
server. You can use the bench to serve multi tenant frappe sites.
|
|
|
|
Installation
|
|
============
|
|
|
|
Easy way
|
|
--------
|
|
|
|
Supported for CentOS 6, Debian 7 and Ubuntu 12.04+
|
|
|
|
`curl https://raw.githubusercontent.com/frappe/bench/master/install_scripts/setup_frappe.sh | sudo bash`
|
|
|
|
This script should install the pre-requisites and add a bench command.
|
|
|
|
|
|
Hard Way
|
|
--------
|
|
|
|
Install pre-requisites,
|
|
|
|
* Python 2.7
|
|
* MariaDB
|
|
* Redis
|
|
* wkhtmltopdf (optional, required for pdf generation)
|
|
|
|
Install bench,
|
|
|
|
git clone https://github.com/frappe/bench
|
|
sudo pip install -e bench
|
|
|
|
Note: Please do not remove the bench directory the above commands will create
|
|
|
|
Migrating from old bench
|
|
------------------------
|
|
|
|
Follow the instructions here, https://github.com/frappe/bench/wiki/Migrating-from-old-bench
|
|
|
|
|
|
Basic Usage
|
|
===========
|
|
|
|
* Create a new bench
|
|
|
|
The init command will create a bench directory with frappe framework
|
|
installed. It will be setup for periodic backups and auto updates once
|
|
a day.
|
|
|
|
bench init erpnext-bench && cd erpnext-bench
|
|
|
|
* Add apps
|
|
|
|
The get-app command gets and installs frappe apps. Examples include
|
|
(erpnext)[https://github.com/frappe/erpnext] and
|
|
(shopping-cart)[https://github.com/frappe/shopping-cart]
|
|
|
|
bench get-app erpnext https://github.com/frappe/erpnext
|
|
|
|
* Add site
|
|
|
|
Frappe apps are run by frappe sites and you will have to create at least one
|
|
site. The new-site command allows you to do that.
|
|
|
|
bench new-site site1.local
|
|
|
|
* Start bench
|
|
|
|
To start using the bench, use the `bench start` command
|
|
|
|
bench start
|
|
|
|
|
|
Updating
|
|
========
|
|
|
|
On initializing a new bench, a cronjob is added to automatically update the bench
|
|
at 1000hrs (as per the time on your machine). You can disable this by running
|
|
`bench config auto_update off` and run `bench config auto_update on` to switch
|
|
it on again. To change the time of update, you will have to edit the cronjob
|
|
manually using `crontab -e`.
|
|
|
|
To manually update the bench, run `bench update` to update all the apps, run
|
|
patches, build JS and CSS files and restart supervisor (if configured to).
|
|
|
|
You can also run the parts of the bench selectively.
|
|
|
|
`bench update --pull` will only pull changes in the apps
|
|
|
|
`bench update --patch` will only run database migrations in the apps
|
|
|
|
`bench update --build` will only build JS and CSS files for the bench
|
|
|
|
`bench update --bench` will only update the bench utility (this project)
|
|
|
|
Running the bench
|
|
==================
|
|
|
|
To run the bench,
|
|
|
|
*For development*: `bench start`
|
|
|
|
*For production*: Configure supervisor and nginx
|
|
|
|
To run the bench, a few services need to be running apart from the processes.
|
|
|
|
External services
|
|
-----------------
|
|
|
|
* MariaDB (Datastore for frappe)
|
|
* Redis (Broker for frappe background workers)
|
|
* nginx (for production deployment)
|
|
* supervisor (for production deployment)
|
|
|
|
Frappe Processes
|
|
----------------
|
|
|
|
* WSGI Server
|
|
|
|
* The WSGI server is responsible for responding to the HTTP requests to
|
|
frappe. In development scenario (`frappe --serve` or `bench start`), the
|
|
Werkzeug WSGI server is used and in production, gunicorn (automatically
|
|
configured in supervisor) is used.
|
|
|
|
* Celery Worker Processes
|
|
|
|
* The Celery worker processes execute background jobs in the Frappe system.
|
|
These processes are automatically started when `bench start` is run and
|
|
for production are configured in supervisor configuration.
|
|
|
|
* Celery Worker Beat Process
|
|
|
|
* The Celery worker beat process schedules enqeueing of scheduled jobs in the
|
|
Frappe system. This process is automatically started when `bench start` is
|
|
run and for production are configured in supervisor configuration.
|
|
|
|
|
|
Production Deployment
|
|
=====================
|
|
|
|
|
|
You can setup the bench for production use by configuring two programs,
|
|
Supervisor and nginx.
|
|
|
|
Supervisor
|
|
----------
|
|
|
|
Supervisor makes sure that the process that power the Frappe system keep running
|
|
and it restarts them if they happen to crash. You can generate the required
|
|
configuration for supervisor using the command `bench setup supervisor`. The
|
|
configuration will be available in `config/supervisor.conf` directory. You can
|
|
then copy/link this file to the supervisor config directory and reload it for it to
|
|
take effect.
|
|
|
|
eg,
|
|
|
|
```
|
|
bench setup supervisor
|
|
sudo ln -s `pwd`/config/supervisor.conf /etc/supervisor/conf.d/frappe.conf
|
|
```
|
|
|
|
The bench will also need to restart the processes managed by supervisor when you
|
|
update the apps. To automate this, you will have to setup sudoers using the
|
|
command, `sudo bench setup sudoers`.
|
|
|
|
Nginx
|
|
-----
|
|
|
|
Nginx is a web server and we use it to serve static files and proxy rest of the
|
|
requests to frappe. You can generate the required configuration for nginx using
|
|
the command `bench setup nginx`. The configuration will be available in
|
|
`config/nginx.conf` file. You can then copy/link this file to the nginx config
|
|
directory and reload it for it to take effect.
|
|
|
|
eg,
|
|
|
|
```
|
|
bench setup supervisor
|
|
sudo ln -s `pwd`/config/nginx.conf /etc/nginx/conf.d/frappe.conf
|
|
```
|
|
|
|
Note: When you restart nginx after the configuration change, it might fail if
|
|
you have another configuration with server block as default for port 80 (in most
|
|
cases for the nginx welcome page). You will have to disable this config. Most
|
|
probable places for it to exist are `/etc/nginx/conf.d/default.conf` and
|
|
`/etc/nginx/conf.d/default`.
|
|
|
|
Multitenant setup
|
|
=================
|
|
|
|
Follow https://github.com/frappe/bench/wiki/Multitenant-Setup
|