accounting/bench
2
0
Fork 0
mirror of https://github.com/frappe/bench.git synced 2024-11-14 09:14:04 +00:00
Code Issues Releases Activity

Merge pull request #207 from vjFaLk/develop-setup

Browse Source 
Updated README
This commit is contained in:
Anand Doshi 2016-04-27 17:37:08 +05:30
commit 821bdb0c6d
1 changed files with 59 additions and 206 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

265
README.md Normal file → Executable file
View File

@ -1,47 +1,76 @@
Bench Bench
===== =====
The bench allows you to setup Frappe / ERPNext apps on your local Linux (CentOS 6, Debian 7 or Ubuntu) machine or a production server. You can use the bench to serve multiple frappe sites. The bench allows you to setup Frappe / ERPNext apps on your local Linux (CentOS 6, Debian 7, Ubuntu, etc) machine or a production server. You can use the bench to serve multiple frappe sites. If you are using a DigitalOcean droplet or any other VPS / Dedicated Server, make sure it has >= 1Gb of ram or has swap setup properly.
To do this install, you must have basic information on how Linux works and should be able to use the command-line. If you are looking easier ways to get started and evaluate ERPNext, [download the Virtual Machine or take a free trial on ERPNext.com](https://erpnext.com/pricing). To do this install, you must have basic information on how Linux works and should be able to use the command-line. If you are looking easier ways to get started and evaluate ERPNext, [download the Virtual Machine](https://erpnext.com/download) or take [a free trial on erpnext.com](https://erpnext.com/pricing).
If you have questions, please ask them on our [forum](https://discuss.erpnext.com/). If you have questions, please ask them on our [forum](https://discuss.erpnext.com/).
Installation Installation
============ ============
Easy Production Setup Production vs Development
--------------------
| Production | Development |
|--------------------------------------------------------------------------|-------------------------------------------------------------------|
| The Production setup uses Nginx and Supervisor | The development setup uses Socketio. |
| This setup isn't meant for instant updates in code. | Any code changes will be reflected instantly. |
| Background services handle all the work, and they start with the system. | You need to explicitly start your server by running `bench start` |
| Uses Celery for job queuing | Uses RQ for queuing |
| Installs with master branch | Installs with develop branch |
Easy Setup
--------------------- ---------------------
> For production use and which also installs ERPNext. Supported for CentOS 6, CentOS 7, Debian 7 and Ubuntu 12.04+ - This is an opinionated setup with logging and SE Linux. So, it is best to setup on a blank server.
> This is an opinionated setup with logging and SE Linux. So, it is best to setup on a blank server. - Supported for CentOS 6, CentOS 7, Debian 7 and Ubuntu 12.04+
- This script will install the pre-requisites, install bench and setup an ERPNext site
- Passwords for Frappe, Frappe Administrator and MariaDB (root) will be generated
- You can then login as **Administrator** with the Administrator password printed
Open your Terminal and enter: Open your Terminal and enter:
####For Production:
``` ```
wget https://raw.githubusercontent.com/frappe/bench/master/install_scripts/setup_frappe.sh wget https://raw.githubusercontent.com/frappe/bench/master/install_scripts/setup_frappe.sh
sudo bash setup_frappe.sh --setup-production sudo bash setup_frappe.sh --setup-production
``` ```
This will install Frappe and ERPNext with Supervisor, Nginx and Celery. Supervisor will keep all services working in the background and make sure they all run.
- This script will install the pre-requisites, install bench and setup an ERPNext site ####For Development:
- This will setup ERPNext with nginx, with Supervisor enabled and checkout the master branch of the ERPNext repo > We recommend using the [Beta Development Setup](#beta-development-setup) if it supports your OS
- Passwords for Frappe, Frappe Administrator and MariaDB (root) will be generated
- You can then login as **Administrator** with the Administrator password printed
If you want to develop ERPNext or any Frappe App, you can omit the "--setup-production" part from the command. This will setup ERPNext as well. Use ```bench start``` to run the server. ```
wget https://raw.githubusercontent.com/frappe/bench/master/install_scripts/setup_frappe.sh
sudo bash setup_frappe.sh --bench-branch develop
```
This will install with Socketio and Redis Queue. You have to explicitly start services by running `bench start`.
> Note: If you are using a DigitalOcean droplet or any other cloud provider's vps, make sure it has >= 1gb of ram or has swap setup properly. ####Script Options:
```
-h | --help
-v | --verbose
--mysql-root-password
--frappe-user
--setup-production
--skip-setup-bench
--skip-install-bench
```
Development Setup (Beta)
Beta Development Setup
------------------------ ------------------------
Tested on Ubuntu 14.04+ and MacOS X. If you find any problems, post them on our forum: [https://discuss.erpnext.com](https://discuss.erpnext.com) Tested on Ubuntu 14.04+, Debian 7+, CentOS 7+, and MacOS X. If you find any problems, post them on our forum: [https://discuss.erpnext.com](https://discuss.erpnext.com)
``` ```
wget https://raw.githubusercontent.com/frappe/bench/develop/playbooks/install.py wget https://raw.githubusercontent.com/frappe/bench/develop/playbooks/install.py
python install.py --develop python install.py --develop
``` ```
This will install with Socketio and Redis Queue. You have to explicitly start services by running `bench start`. This script requires Python2.7+ installed on your machine. You need to run this with a user that is **not** `root`, but can `sudo`. If you don't have such a user, you can search the web for *How to add a new user in { your OS }* and *How to add an existing user to sudoers in { your OS }*.
This script requires Python2.7+ installed on your machine. You need to run this with a user that is **not** `root`, but can `sudo`. If you don't have such a user, you can search the web for *How to add a new user in { your OS }* and *How to add an existing user to sudoers in { your OS }*.
This script will: This script will:
@ -57,97 +86,6 @@ This script will:
You will have to manually create a new site (`bench new-site`) and get apps that you need (`bench get-app`, `bench install-app`). You will have to manually create a new site (`bench new-site`) and get apps that you need (`bench get-app`, `bench install-app`).
Manual Install
--------------
Install pre-requisites,
* [Python 2.7](https://www.python.org/download/releases/2.7/)
* [MariaDB](https://mariadb.org/)
* [Redis](http://redis.io/topics/quickstart)
* [WKHTMLtoPDF with patched QT](http://wkhtmltopdf.org/downloads.html) (required for pdf generation)
[Installing pre-requisites on OSX](https://github.com/frappe/bench/wiki/Installing-Bench-Pre-requisites-on-MacOSX)
Install bench as a *non root* user,
git clone https://github.com/frappe/bench bench-repo
sudo pip install -e bench-repo
Note: Please do not remove the bench directory the above commands will create
Initialize Bench using: `bench init frappe-bench`. Here you can replace `frappe-bench` with a name of your choice for your bench.
Installing ERPNext
------------------
If you're here to setup ERPNext, continue with [ERPNext setup](https://github.com/frappe/bench#setting-up-erpnext)
Migrating from existing installation
------------------------------------
If want to migrate from ERPNext version 3, follow the instructions here, https://github.com/frappe/bench/wiki/Migrating-from-ERPNext-version-3
If want to migrate from the 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 frappe-bench && cd frappe-bench
* Add apps
The get-app command gets and installs frappe apps. Examples include
- [erpnext](https://github.com/frappe/erpnext)
- [erpnext_shopify](https://github.com/frappe/erpnext_shopify)
- [paypal_integration](https://github.com/frappe/paypal_integration)
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
To login to Frappe / ERPNext, open your browser and go to `localhost:8000`
The default user name is "Administrator" and password is what you set when you created the new site.
Setting Up ERPNext
==================
To setup a bench that runs ERPNext, run the following commands
```
cd ~
bench init frappe-bench
cd frappe-bench
bench get-app erpnext https://github.com/frappe/erpnext # Add ERPNext to your bench apps
bench new-site site1.local # Create a new site
bench install-app erpnext # Install ERPNext for the site
```
You can now either use `bench start` or setup the bench for production use.
Updating Updating
======== ========
@ -165,107 +103,22 @@ You can also run the parts of the bench selectively.
`bench update --bench` will only update the bench utility (this project) `bench update --bench` will only update the bench utility (this project)
Running the bench
==================
To run the bench, Guides
=======
*For development*: `bench start` - [Configuring HTTPS](https://frappe.github.io/frappe/user/en/bench/guides/configuring-https.html)
- [Diagnosing the Scheduler](https://frappe.github.io/frappe/user/en/bench/guides/diagnosing-the-scheduler.html)
*For production*: Configure supervisor and nginx - [Change Hostname](https://frappe.github.io/frappe/user/en/bench/guides/how-to-change-host-name-from-localhost.html)
- [Manual Setup](https://frappe.github.io/frappe/user/en/bench/guides/manual-setup.html)
To run the bench, a few services need to be running apart from the processes. - [Setup Production](https://frappe.github.io/frappe/user/en/bench/guides/setup-production.html)
- [Setup Multitenancy](https://frappe.github.io/frappe/user/en/bench/guides/setup-multitenancy.html)
External services - [Setup SSL](https://frappe.github.io/frappe/user/en/bench/guides/setup-ssl.html)
----------------- - [Stopping Production](https://frappe.github.io/frappe/user/en/bench/guides/stop-production-and-start-development.html)
* MariaDB (Datastore for frappe)
* Redis (Queue for frappe background workers and caching)
* 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 (`bench 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 Resources
===================== =======
- [Background Services](https://frappe.github.io/frappe/user/en/bench/resources/background-services.html)
You can setup the bench for production use by configuring two programs, Supervisor and nginx. - [Bench Commands Cheat Sheet](https://frappe.github.io/frappe/user/en/bench/resources/bench-commands-cheatsheet.html)
- [Bench Procfile](https://frappe.github.io/frappe/user/en/bench/resources/bench-procfile.html)
> These steps are automated if you pass `--setup-production` to the easy install script
> or run `sudo bench setup production`
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-bench.conf
```
Note: For CentOS 7, the extension should be `ini`, thus the command becomes
```
bench setup supervisor
sudo ln -s `pwd`/config/supervisor.conf /etc/supervisor/conf.d/frappe-bench.ini #for CentOS 7 only
```
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 $(whoami)`.
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 nginx
sudo ln -s `pwd`/config/nginx.conf /etc/nginx/conf.d/frappe-bench.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