diff --git a/README.md b/README.md old mode 100644 new mode 100755 index 1bb21a54..837724e8 --- a/README.md +++ b/README.md @@ -1,47 +1,76 @@ 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/). 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: + +####For Production: ``` wget https://raw.githubusercontent.com/frappe/bench/master/install_scripts/setup_frappe.sh 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 -- This will setup ERPNext with nginx, with Supervisor enabled and checkout the master branch of the ERPNext repo -- Passwords for Frappe, Frappe Administrator and MariaDB (root) will be generated -- You can then login as **Administrator** with the Administrator password printed +####For Development: +> We recommend using the [Beta Development Setup](#beta-development-setup) if it supports your OS -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 python install.py --develop ``` - -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 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 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`). -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 ======== @@ -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) -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 (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. +Guides +======= +- [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) +- [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) +- [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) +- [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) -Production Deployment -===================== +Resources +======= - -You can setup the bench for production use by configuring two programs, Supervisor and nginx. - -> 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 +- [Background Services](https://frappe.github.io/frappe/user/en/bench/resources/background-services.html) +- [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)