Added Bench Documentation

frappe/docs/user/en/bench/guides/diagnosing-the-scheduler.md

@@ -0,0 +1,59 @@
+<!-- markdown -->
+
+If you're experiencing delays in scheduled jobs or they don't seem to run, you can run the several commands to diagnose the issue.
+
+### `bench doctor`
+
+This will output the following in order:
+- Worker Status
+- Scheduler Status per site
+- Pending Tasks
+- Timed out locks
+
+Desirable output:
+
+	Workers online: True
+	Pending tasks 0
+	Timed out locks:
+
+
+### `bench celery-doctor`
+
+This will output the following in order:
+- Queue Status
+- Running Tasks
+
+Desirable output:
+
+	Queue Status
+	------------
+	[
+	 {
+	  "total": 0
+	 }
+	]
+
+	Running Tasks
+	------------
+	{
+	 "async@erpnext": [],
+	 "longjobs@erpnext": [],
+	 "jobs@erpnext": []
+	}
+
+
+### `bench dump-queue-status`
+
+This will output detailed diagnostic information for task queues in JSON
+
+Desirable output:
+
+
+	[
+	 {
+	  "total": 0
+	 }
+	]
+	Pending Tasks Queue
+	--------------------
+

frappe/docs/user/en/bench/guides/index.md

@@ -0,0 +1 @@
+{index}

frappe/docs/user/en/bench/guides/index.txt

@@ -0,0 +1,9 @@
+configuring-https
+diagnosing-the-scheduler
+how-to-change-host-name-from-localhost
+manual-setup
+setup-multitenancy
+setup-production
+setup-ssl
+stop-production-and-start-development
+updating

frappe/docs/user/en/bench/guides/manual-setup.md

@@ -0,0 +1,79 @@
+Manual Setup
+--------------
+
+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
+
+
+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:
+	
+	- [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 install ERPNext, simply run:
+```
+bench install-app erpnext
+```
+
+You can now either use `bench start` or [setup the bench for production use](setup-production.html)
+
+
+

frappe/docs/user/en/bench/guides/setup-multitenancy.md

@@ -0,0 +1,56 @@
+Assuming that you've already got your first site running and you've performed
+the [production deployment steps](production-setup.html), this section explains how to host your second
+site (and more). Your first site is automatically set as default site. You can
+change it with the command,
+	
+	bench use sitename
+
+
+
+
+Port based multitenancy
+-----------------------
+
+DNS based multitenancy mode is enabled by default, switch it off using the command
+```
+	bench config dns_multitenant off
+```
+
+You can create a new site and make run it on a different port (while the first
+one runs on port 80).
+
+* Create a new site
+
+	`bench new-site site2name`
+
+* Set port
+
+	`bench set-nginx-port site2name 82`
+
+* Re generate nginx config
+
+	`bench setup nginx`
+
+* Reload nginx
+
+	`sudo service nginx reload`
+
+
+DNS based multitenancy
+----------------------
+
+You can name your sites as the hostnames that would resolve to it. Thus, all the sites you add to the bench would run on the same port and will be automatically selected based on the hostname. 
+
+To make a new site under DNS based multitenancy, perform the following steps.
+
+* Create a new site
+
+	`bench new-site site2name`
+
+* Re generate nginx config
+
+	`bench setup nginx`
+
+* Reload nginx
+
+	`sudo service nginx reload`

frappe/docs/user/en/bench/guides/setup-production.md

@@ -0,0 +1,56 @@
+You can setup the bench for production use by configuring two programs, Supervisor and nginx. If you want to revert your Production Setup to Development Setup refer to [these commands](https://github.com/frappe/bench/wiki/Stopping-Production-and-starting-Development)
+
+####Easy Production Setup
+These steps are automated if you pass `--setup-production` to the easy install script 
+or run `sudo bench setup production`
+
+
+####Manual Production Setup
+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`.

frappe/docs/user/en/bench/guides/stop-production-and-start-development.md

@@ -0,0 +1,20 @@
+Moving back to a Development setup is pretty easy
+
+Change directory to your bench directory
+
+	cd frappe-bench
+
+Remove supervisor and nginx configs
+
+	rm config/supervisor.conf
+	rm config/nginx.conf
+
+Stop running services
+
+	sudo service nginx stop
+	sudo service supervisord stop
+	
+Setup procfile again and start bench
+
+	bench setup procfile
+	bench start

frappe/docs/user/en/bench/index.md

@@ -0,0 +1 @@
+{index}

frappe/docs/user/en/bench/index.txt

@@ -0,0 +1 @@
+guides

frappe/docs/user/en/bench/resources/background-services.md

@@ -0,0 +1,30 @@
+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.

frappe/docs/user/en/bench/resources/bench-commands-cheatsheet.md

@@ -0,0 +1,74 @@
+### General Usage
+* `bench --help` - Show all commands and help
+* `bench [command] --help` - Show help for command
+* `bench --site [site-name] COMMAND` - Specify site for command
+* `bench update` - Pulls changes for bench-repo and all apps, applies patches, builds JS and CSS, and then migrates.
+  * `--pull`                Pull changes in all the apps in bench
+  * `--patch`               Run migrations for all sites in the bench
+  * `--build`               Build JS and CSS artifacts for the bench
+  * `--bench`               Update bench
+  * `--requirements`        Update requirements
+  * `--restart-supervisor`  restart supervisor processes after update
+  * `--upgrade` Does major upgrade (Eg. ERPNext 6 -> 7)
+  * `--no-backup`			  Don't take a backup before update
+* `bench migrate` Will read JSON files and make changes to the database accordingly
+
+###Config
+* `bench config` - Change bench configuration
+  * `auto_update [on/off]`                   Enable/Disable auto update for bench
+  * `dns_multitenant [on/off]`               Enable/Disable DNS Multitenancy
+  * `http_timeout [?]`                  Set http timeout
+  * `restart_supervisor_on_update`  Enable/Disable auto restart of supervisor
+  * `serve_default_site`            Configure nginx to serve the default site on
+  * `update_bench_on_update`        Enable/Disable bench updates on running bench...
+* `bench setup` - Setup components
+  * `auto-update`  Add cronjob for bench auto update
+  * `backups    `  Add cronjob for bench backups
+  * `config     `  overwrite or make config.json
+  * `env        `  Setup virtualenv for bench
+  * `nginx      `  generate config for nginx
+  * `procfile   `  Setup Procfile for bench start
+  * `production `  setup bench for production
+  * `redis      `  generate config for redis cache
+  * `socketio   `  Setup node deps for socketio server
+  * `sudoers    `  Add commands to sudoers list for execution...
+  * `supervisor `  generate config for supervisor
+
+
+###Development
+* `bench new-app [app-name]` Creates a new app 
+* `bench get-app [app-name] [repo-link]` - Downloads an app from an online git repository and installs it
+* `bench install-app [app-name]` Installs existing app
+* `bench remove-from-installed-apps [app-name]` Remove app from the list of apps
+* `bench uninstall-app [app-name]` Delete app and everything linked to the app
+* `bench new-site [sitename]` - Creates a new site
+  * `--db-name`                Database name
+  * `--mariadb-root-username`  Root username for MariaDB
+  * `--mariadb-root-password`  Root password for MariaDB
+  * `--admin-password`         Administrator password for new site
+  * `--verbose`                     Verbose
+  * `--force`                       Force restore if site/database already exists
+  * `--source_sql`             Initiate database with a SQL file
+  * `--install-app`            Install app after installation`
+* `bench use [site]` Sets a default site
+* `bench drop-site` - Removes site from disk and database completely
+  * `--root-login` 
+  * `--root-password`
+* `bench console` - Opens a IPython console in the bench venv
+* `bench execute` - Execute a method inside any app.
+  * Eg : `bench execute frappe.utils.scheduler.enqueue_scheduler_events`
+* `bench mysql` - Opens SQL Console 
+* `bench run-tests` - Run tests
+  * `--app` App Name
+  * `--doctype` DocType to run tests for
+  * `--test` Specific Test
+  * `--module` Run a particular module that has tests 
+  * `--profile` Runs a Python profiler on the test
+
+
+
+###Scheduler 
+* `bench enable-scheduler` - Enables Scheduler that will run scheduled tasks
+* `bench doctor` - Get diagnostic info about background workers 
+* `bench show-pending-jobs`- Get pending jobs
+* `bench purge-jobs` - Destroy all pending jobs

frappe/docs/user/en/bench/resources/bench-procfile.md

@@ -0,0 +1,28 @@
+`bench start` uses [honcho](http://honcho.readthedocs.org) to manage multiple processes in **developer mode**.
+
+### Processes
+
+The various process that are needed to run frappe are:
+
+1. `bench start` - the web server
+2. celery task queue for background workers (scheduled jobs and other async tasks)
+3. celery worker beat to trigger periodic tasks
+4. `redis` for caching (general)
+5. `redis` for managing queue for background workers
+6. `redis` as a message broker for real-time updates / updates from background workers
+7. `node` to run `socketio` for real-time messaging.
+
+Optionally if you are developing for frappe you can add:
+
+`bench watch` to automatically build the desk javascript app.
+
+### Sample
+
+	web: bench --site test.erpnext.com serve --port 8001
+	redis_async_broker: redis-server config/redis_async_broker.conf
+	socketio: node apps/frappe/socketio.js
+	workerbeat: sh -c 'cd sites && exec ../env/bin/python -m frappe.celery_app beat -s scheduler.schedule'
+	worker: sh -c 'cd sites && exec ../env/bin/python -m frappe.celery_app worker'
+	redis_cache: redis-server config/redis_cache.conf
+	redis: redis-server
+	watch: bench watch

frappe/docs/user/en/bench/resources/index.md

@@ -0,0 +1 @@
+{index}

frappe/docs/user/en/bench/resources/index.txt

@@ -0,0 +1,3 @@
+background-services
+bench-commands-cheatsheet
+bench-procfile

frappe/docs/user/en/guides/deployment/checking-problems-in-bench.md

@@ -1,15 +0,0 @@
-<!-- markdown -->
-
-If you're experiencing delays in scheduled jobs or they don't seem to run, you run run the following command to diagnose the issue.
-
-`bench doctor`
-
-A desirable output is like below
-
-
-	Workers online: True
-	Pending tasks 0
-	Timed out locks:
-
-
-We'll be adding more health checks soon.

frappe/docs/user/en/guides/deployment/email-notifications-for-failed-background-jobs.md

@@ -1,4 +1,4 @@
-
+<!-- markdown -->
 
 <p>Frappe handles failure of jobs in the following way,</p><p>1) If a job fails, (raises exception), it's logged in Scheduler Log and&nbsp; <code>logs/worker.error.log</code>.<br>2) Keeps a lock file and would not run anymore if lock file is there.<br>3) Raises LockTimeoutError in case the lock file is more than 10 minutes old.</p>
 

frappe/docs/user/en/guides/deployment/how-to-enable-social-logins.md

@@ -3,7 +3,7 @@ Use Facebook, Google or GitHub authentication to login to Frappe, and your users
 The system uses the **Email ID** supplied by these services to **match with an existing user** in Frappe. If no such user is found, **a new user is created** of the default type **Website User**, if Signup is not disabled in Website Settings. Any System Manager can later change the user type from **Website User** to **System User**, so that the user can access the Desktop.
 
 <figure class="text-center">
-	<img src="/assets/frappe_io/images/how-to/social-logins-1.png"
+	<img src="/assets/img/social-logins-1.jpg"
 		alt="Login screen with Social Logins enabled">
 	<figcaption>Login screen with Social Logins enabled</figcaption>
 </figure>

frappe/docs/user/en/guides/deployment/index.txt

@@ -1,7 +1,4 @@
 migrations
 how-to-migrate-doctype-changes-to-production
-how-to-change-host-name-from-localhost
-configuring-https
-checking-problems-in-bench
 email-notifications-for-failed-background-jobs
 how-to-enable-social-logins

frappe/docs/user/en/index.txt

@@ -1,3 +1,4 @@
 tutorial
+bench
 guides
 videos