refactor: bench readme and rename license file

README.md

@@ -1,131 +1,236 @@
 <div align="center">
 	<img src="https://github.com/frappe/design/raw/master/logos/png/bench-logo.png" height="128">
-	<h2>bench</h2>
+	<h2>Bench</h2>
 </div>
 
-bench is a command-line utility that helps you to install apps, manage multiple sites and update Frappe / ERPNext apps on */nix (macOS, Ubuntu, Debian, CentOS, etc) for development and production.
+Bench is a command-line utility that helps you to install, update, and manage multiple sites for Frappe/ERPNext applications on [*nix systems](https://en.wikipedia.org/wiki/Unix-like) for development and production.
 
+## Table of Contents
 
-> **Note**: If you are looking for 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).
+ - [Installation](#installation)
+	- [Docker Installation](#docker-installation)
+		- [Development Setup](#docker-installation-for-development)
+		- [Production Setup](#docker-installation-for-production)
+	- [Easy Install Script](#easy-install-script)
+	- [Manual Installation](#manual-installation)
+ - [Usage](#usage)
+ - [Custom Bench commands](#custom-bench-commands)
+ - [Bench Manager](#bench-manager)
+ - [Guides](#guides)
+ - [Resources](#resources)
+ - [License](#license)
+
+
+## Installation
 
----
+A typical bench setup provides two types of environments &mdash; Development and Production.
 
-# Table of Contents
+The setup for each of these installations can be achieved in multiple ways:
 
- - [bench CLI](#bench-cli)
-	- [Usage](#usage)
-	- [Installation](#installation)
-	- [Custom Bench commands](#custom-bench-commands)
+ - [Docker Installation](#docker-installation)
  - [Easy Install Script](#easy-install-script)
- - [Release Bench](#release-bench)
- - [Guides](#guides)
- - [Resources](#resources)
- - [License](#license)
----
+ - [Manual Installation](#manual-installation)
 
-# bench CLI
+We recommend using either the Docker Installation or the Easy Install Script to setup a Production Environment. For Development, you may choose either of the three methods to setup an instance.
 
-Bench is a command line tool that helps you install, setup, manage multiple sites and apps based on Frappe Framework.
+Otherwise, if you are looking to evaluate ERPNext, you can also download the [Virtual Machine Image](https://erpnext.com/download) or register for [a free trial on erpnext.com](https://erpnext.com/pricing).
 
----
 
-## Usage
+### Docker Installation
 
-* Create a new bench
+A Frappe/ERPNext instance can be setup and replicated easily using [Docker](https://docker.com). The officially supported Docker installation can be used to setup either of both Development and Production environments.
 
-		bench init [bench-name]
+To setup either of the environments, you will need to clone the official docker repository:
 
-* Add a site under current bench
+```sh
+$ git clone https://github.com/frappe/frappe_docker.git
+$ cd frappe_docker
+```
 
-		bench new-site [site-name]
+A quick setup guide for both the envionments can be found below. For more details, check out the [Frappe/ERPNext Docker Repository](https://github.com/frappe/frappe_docker).
 
-	**Optional**: If the database for the site does not reside on localhost or listens on a custom port, you can use the flags `--db-host` to set a custom host and/or `--db-port` to set a custom port.
+#### Docker Installation for Development
 
-		bench new-site [site-name] --db-host [custom-db-host-ip] --db-port [custom-db-port]
+To setup a development environment for Docker, follow the [Frappe/ERPNext Docker for Development Guide](https://github.com/frappe/frappe_docker/blob/develop/development/README.md).
 
-* Add apps to bench
+#### Docker Installation for Production
 
-		bench get-app [app-name] [app-link]
+Copy the `env-example` file to `.env`
 
-* Install apps on a particular site
+```sh
+$ cp installation/env-example installation/.env
+```
 
-		bench --site [site-name] install-app [app-name]
+Make a directory for handling sites:
 
-* Start bench (only for development)
+```sh
+$ mkdir installation/sites
+```
 
-		bench start
+Optionally, you may also setup an [NGINX Proxy for SSL Certificates](https://github.com/evertramos/docker-compose-letsencrypt-nginx-proxy-companion) with auto-renewal for your Production instance. We recommend this for instances being accessed over the internet. For this to work, the DNS needs to be configured correctly so that [LetsEncrypt](https://letsencrypt.org) can verify the domain. To setup the proxy, run the following commands:
 
-* Show bench help
+```sh
+$ git clone https://github.com/evertramos/docker-compose-letsencrypt-nginx-proxy-companion.git
+$ cd docker-compose-letsencrypt-nginx-proxy-companion
+$ cp .env.sample .env
+$ ./start.sh
+```
 
-		bench --help
+To get the Production instance running, run the following command:
 
-_Note:_ Apart from `bench init`, all other bench commands have to be run having the respective bench directory as the working directory. _(`bench update` may also be run, but it's behaviour is covered in depth in the docs)_
+```sh
+$ docker-compose \
+    --project-name <project-name> \
+    -f installation/docker-compose-common.yml \
+    -f installation/docker-compose-erpnext.yml \
+    -f installation/docker-compose-networks.yml \
+    --project-directory installation up -d
+```
 
-For more in depth information on commands and usage follow [here](https://github.com/frappe/bench/blob/master/docs/commands_and_usage.md). As for a consolidated list of bench commands, go through [this page](https://github.com/frappe/bench/blob/master/docs/bench_usage.md).
+Make sure to replace `<project-name>` with whatever you wish to call it. This should get the instance running through docker. Now, to create a new site on the instance you may run:
 
----
+```sh
+docker exec -it \
+    -e "SITE_NAME=$SITE_NAME" \
+    -e "DB_ROOT_USER=$DB_ROOT_USER" \
+    -e "MYSQL_ROOT_PASSWORD=$MYSQL_ROOT_PASSWORD" \
+    -e "ADMIN_PASSWORD=$ADMIN_PASSWORD" \
+    -e "INSTALL_APPS=erpnext" \ # optional, if you want to install any other apps
+    <project-name>_erpnext-python_1 docker-entrypoint.sh new
+```
 
-## Installation
+Once this is done, you may access the instance at `$SITE_NAME`.
 
-To do this install, you must have basic information on how Linux works and should be able to use the command-line. bench will also create nginx and supervisor config files, setup backups and much more. If you are using on a VPS make sure it has >= 1Gb of RAM or has swap setup properly.
+**Note:** The Production setup does not contain, require, or use bench. For a list of substitute commands, check out the [Frappe/ERPNext Docker Site Operations](https://github.com/frappe/frappe_docker/#site-operations).
 
-	git clone https://github.com/frappe/bench ~/.bench
-	pip3 install --user -e ~/.bench
 
-As bench is a python application, its installation really depends on `python` + `pip` + `git`. The Frappe Framework, however has various other system dependencies like `nodejs`, `yarn`, `redis` and a database system like `mariadb` or `postgres`. Go through the [installation requirements](https://github.com/frappe/bench/blob/master/docs/installation.md) for an updated list.
+### Easy Install Script
 
-If you have questions, please ask them on the [forum](https://discuss.erpnext.com/c/bench) under the "Install / Update" category.
+The Easy Install script should get you going with a Frappe/ERPNext setup with minimal manual intervention and effort. Since there are a lot of configurations being automatically setup, we recommend executing this script on a fresh server.
 
----
+**Note:** This script works only on GNU/Linux based server distributions, and has been designed and tested to work on Ubuntu 16.04+, CentOS 7+, and Debian-based systems.
 
-## Custom Bench Commands
+#### Prerequisites
+
+You need to install the following packages for the script to run:
+
+ - ##### Ubuntu and Debian-based Distributions:
+
+	```sh
+	$ apt install python3-minimal build-essential python3-setuptools
+	```
+
+ - ##### CentOS and other RPM Distributions:
+
+	```sh
+	$ dnf groupinstall "Development Tools"
+	$ dnf install python3
+	```
+
+#### Setup
+
+Download the Easy Install script and execute it:
+
+```sh
+$ wget https://raw.githubusercontent.com/frappe/bench/master/playbooks/install.py
+$ python3 install.py --production
+```
+
+The script should then prompt you for the MySQL root password and an Administrator password for the Frappe/ERPNext instance, which will then be saved under `$HOME/passwords.txt` of the user used to setup the instance. This script will then install the required stack, setup bench and a default ERPNext instance.
+
+When the setup is complete, you will be able to access the system at `http://<your-server-ip>`, wherein you can use the administrator password to login.
+
+#### Troubleshooting
+
+In case the setup fails, the log file is saved under `/tmp/logs/install_bench.log`. You may then: 
 
-Want to utilize a bench command you've added in your custom Frappe application? [This](https://github.com/frappe/bench/blob/master/docs/bench_custom_cmd.md) guide might be of some help.
+ - Create an Issue in this repository with the log file attached.
+ - Search for an existing issue or post the log file on the [Frappe/ERPNext Discuss Forum](https://discuss.erpnext.com/c/bench) with the tag `installation_problem` under "Install/Update" category.
 
----
+For more information and advanced setup instructions, check out the [Easy Install Documentation](https://github.com/frappe/bench/blob/master/docs/easy_install.md).
 
-# Easy Install Script
 
-- This is an opinionated setup so it is best to setup on a blank server.
-- Works on Ubuntu 16.04+, CentOS 7+, Debian 8+
-- You may have to install Python 3 and other essentials by running `apt-get install python3-minimal build-essential python3-setuptools`
-- This script will install the pre-requisites, install bench and setup an ERPNext site `(site1.local under frappe-bench)`
-- Passwords for Frappe Administrator and MariaDB (root) will be asked and saved under `~/passwoords.txt`
-- MariaDB (root) password may be `password` on a fresh server
-- You can then login as **Administrator** with the Administrator password
-- The log file is saved under `/tmp/logs/install_bench.log` in case you run into any issues during the install.
-- If you find any problems, post them on the forum: [https://discuss.erpnext.com](https://discuss.erpnext.com/c/bench) with the `installation_problem` under "Install / Update" category.
+### Manual Installation
 
-		wget https://raw.githubusercontent.com/frappe/bench/master/playbooks/install.py
-		python3 install.py --production
+Although not recommended, some might want to manually setup a bench instance locally for development. To quickly get started on installing bench the hard way, you can follow [Installing Bench and Frappe](https://frappe.io/docs/user/en/installation).
 
-Follow [Easy Install Docs](https://github.com/frappe/bench/blob/master/docs/easy_install.md) for more information.
+For more extensive distribution-dependent documentation, check out the following guides:
 
----
+ - [Hitchhiker's Guide to Installing Frappe on Linux](https://github.com/frappe/frappe/wiki/The-Hitchhiker%27s-Guide-to-Installing-Frappe-on-Linux)
+ - [Hitchhiker's Guide to Installing Frappe on MacOS](https://github.com/frappe/frappe/wiki/The-Hitchhiker%27s-Guide-to-Installing-Frappe-on-Mac-OS-X)
 
-# Release Bench
 
-Releases can be made for [Frappe](https://github.com/frappe/frappe) apps using bench. More information about this process can be found [here](https://github.com/frappe/bench/blob/master/docs/releasing_frappe_apps.md).
+## Basic Usage
 
----
+**Note:** Apart from `bench init`, all other bench commands are expected to be run in the respective bench directory.
 
-# Bench Manager (GUI for Bench)
+ * Create a new bench:
 
-[Bench Manager](https://github.com/frappe/bench_manager) is a graphical user interface to emulate the functionalities of Frappe Bench. Like the command line utility it helps you install apps, manage multiple sites, update apps and much more. Install just by executing the following command in the respective bench directory.
+	```sh
+	$ bench init [bench-name]
+	```
 
-		bench setup manager
+ * Add a site under current bench:
 
----
+	```sh
+	$ bench new-site [site-name]
+	```
+	- **Optional**: If the database for the site does not reside on localhost or listens on a custom port, you can use the flags `--db-host` to set a custom host and/or `--db-port` to set a custom port.
 
-# Docker
+		```sh
+		$ bench new-site [site-name] --db-host [custom-db-host-ip] --db-port [custom-db-port]
+		```
 
-- For official images and resources [Frappe Docker](https://github.com/frappe/frappe_docker)
-- Production Installation [README](https://github.com/frappe/frappe_docker/blob/develop/README.md)
-- Developer Setup [README](https://github.com/frappe/frappe_docker/blob/develop/development/README.md)
+ * Download and add applications to bench:
 
----
+	```sh
+	$ bench get-app [app-name] [app-link]
+	```
 
-# Guides
+ * Install apps on a particular site
+
+	```sh
+	$ bench --site [site-name] install-app [app-name]
+	```
+
+ * Start bench (only for development)
+
+	```sh
+	$ bench start
+	```
+
+ * Show bench help:
+
+	```sh
+	$ bench --help
+	```
+
+
+For more in-depth information on commands and their usage, follow [Commands and Usage](https://github.com/frappe/bench/blob/master/docs/commands_and_usage.md). As for a consolidated list of bench commands, check out [Bench Usage](https://github.com/frappe/bench/blob/master/docs/bench_usage.md).
+
+
+## Custom Bench Commands
+
+If you wish to extend the capabilities of bench with your own custom Frappe Application, you may follow [Adding Custom Bench Commands](https://github.com/frappe/bench/blob/master/docs/bench_custom_cmd.md).
+
+
+## Bench Manager
+
+[Bench Manager](https://github.com/frappe/bench_manager) is a GUI frontend for Bench with the same functionalties. You can install it by executing the following command:
+
+```sh
+$ bench setup manager
+```
+
+ - **Note:** This will create a new site to setup Bench Manager, if you want to set it up on an existing site, run the following commands:
+
+	```sh
+	$ bench get-app https://github.com/frappe/bench_manager.git
+	$ bench --site <sitename> install-app bench_manager
+	```
+
+
+## Guides
 
 - [Configuring HTTPS](https://frappe.io/docs/user/en/bench/guides/configuring-https.html)
 - [Using Let's Encrypt to setup HTTPS](https://frappe.io/docs/user/en/bench/guides/lets-encrypt-ssl-setup.html)
@@ -136,16 +241,18 @@ Releases can be made for [Frappe](https://github.com/frappe/frappe) apps using b
 - [Setup Multitenancy](https://frappe.io/docs/user/en/bench/guides/setup-multitenancy.html)
 - [Stopping Production](https://github.com/frappe/bench/wiki/Stopping-Production-and-starting-Development)
 
----
+For an exhaustive list of guides, check out [Bench Guides](https://frappe.io/docs/user/en/bench/guides).
 
-# Resources
 
-- [Background Services](https://frappe.io/docs/user/en/bench/resources/background-services.html)
+## Resources
+
 - [Bench Commands Cheat Sheet](https://frappe.io/docs/user/en/bench/resources/bench-commands-cheatsheet.html)
+- [Background Services](https://frappe.io/docs/user/en/bench/resources/background-services.html)
 - [Bench Procfile](https://frappe.io/docs/user/en/bench/resources/bench-procfile.html)
 
----
+For an exhaustive list of resources, check out [Bench Resources](https://frappe.io/docs/user/en/bench/resources).
+
 
-# License
+## License
 
-bench is licensed under [GNU GPLv3](LICENSE)
+This repository has been released under the [GNU GPLv3 License](LICENSE).