Merge pull request #117 from revant/fix-readme

fix: Improve README(s)

README.md

@@ -8,6 +8,8 @@ This docker installation takes care of the following:
 * Setting up all the system requirements: eg. MariaDB, Node, Redis.
 * [OPTIONAL] Configuring networking for remote access and setting up LetsEncrypt
 
+For docker based development refer this [README](development/README.md)
+
 ## Deployment
 
 ### Setting up Pre-requisites
@@ -53,45 +55,62 @@ To get started, copy the existing `env-example` file to `.env` inside the `insta
     - Email for LetsEncrypt expiry notification. This is only required if you are setting up LetsEncrypt.
 
 
-### Deployment for local development
+### Local deployment
 
-To start the Frappe/ERPNext services for production, run the following command:
+For trying out locally or to develop apps using ERPNext ReST API port 80 must be published.
+First start the containers and then run an additional command to publish port of *-nginx container.
+
+To start and publish Frappe/ERPNext services as local api, run the following commands:
 
 For Erpnext:
 
-
 ```sh
-docker-compose \ 
+# Start services
+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
-    --project-directory installation run --publish 80:80 erpnext-nginx
+
+# Publish port
+docker-compose \
+    --project-name <project-name> \
+    -f installation/docker-compose-common.yml \
+    -f installation/docker-compose-erpnext.yml \
+    --project-directory installation run --publish 80:80 -d erpnext-nginx
 ```
 
 For Frappe:
+
 ```sh
-docker-compose \ 
+# Start services
+docker-compose \
     --project-name <project-name> \
     -f installation/docker-compose-common.yml \
     -f installation/docker-compose-frappe.yml \
-    -f installation/docker-compose-networks.yml \
+    --project-directory installation up -d
-    --project-directory installation run --publish 80:80 frappe-nginx
+
+# Publish port
+docker-compose \
+    --project-name <project-name> \
+    -f installation/docker-compose-common.yml \
+    -f installation/docker-compose-frappe.yml \
+    --project-directory installation run --publish 80:80 -d frappe-nginx
 ```
 
 Make sure to replace `<project-name>` with any desired name you wish to set for the project.
 
-Note: this command does not run docker-compose in daemon mode. You will need to keep the terminal window open.
+Note:
-Note: the local deployment is for testing only. The site names are limited to patterns matching \*.localhost.
+ - This command adds an additional container for frappe-nginx with published ports.
-
+ - The local deployment is for testing and REST API development purpose only.
+ - The site names are limited to patterns matching \*.localhost by default
+ - Additional site name patterns can be added to /etc/hosts of desired container or host
 
 ### Deployment for production
 
 #### Setup Letsencrypt Nginx Proxy Companion
 
-
+Letsencrypt Nginx Proxy Companion can optionally be setup to provide SSL. This is recommended for instances accessed over the internet.
-
-Letsencrypt Nginx Proxy Companion can optionally be setup to provide SSL. This is recommended for istances accessed over the internet. 
 
 Your DNS will need to be configured correctly in order for Letsencrypt to verify your domain.
 
@@ -106,8 +125,7 @@ cp .env.sample .env
 ```
 
 For more details, see: https://github.com/evertramos/docker-compose-letsencrypt-nginx-proxy-companion
-Letsencrypt Nginx Proxy Companion works by automatically proxing to containers with the `VIRTUAL_HOST` environmental variable.
+Letsencrypt Nginx Proxy Companion works by automatically proxying to containers with the `VIRTUAL_HOST` environmental variable.
-
 
 #### Start Frappe/ERPNext Services
 
@@ -125,7 +143,6 @@ docker-compose \
 Make sure to replace `<project-name>` with any desired name you wish to set for the project.
 Note: use `docker-compose-frappe.yml` in case you need only Frappe without ERPNext.
 
-
 ### Docker containers
 
 This repository contains the following docker-compose files each one containing the described images:
@@ -139,26 +156,26 @@ This repository contains the following docker-compose files each one containing
     * mariadb: main database
         * volume: mariadb-vol
 * docker-compose-erpnext.yml
-    * erpnext-nginx: serves static assets and proxies web request to the appropriate container, allowing to offer all services on the same port. 
+    * erpnext-nginx: serves static assets and proxies web request to the appropriate container, allowing to offer all services on the same port.
         * volume: assets
     * erpnext-python: main application code
-    * frappe-socketio: enables realtime comunication to the user interface through websockets
+    * frappe-socketio: enables realtime communication to the user interface through websockets
     * frappe-worker-default: background runner
     * frappe-worker-short: background runner for short-running jobs
     * frappe-worker-long: background runner for long-running jobs
     * frappe-schedule
 
 * docker-compose-frappe.yml
-    * frappe-nginx: serves static assets and proxies web request to the appropriate container, allowing to offer all services on the same port. 
+    * frappe-nginx: serves static assets and proxies web request to the appropriate container, allowing to offer all services on the same port.
         * volume: assets
     * erpnext-python: main application code
-    * frappe-socketio: enables realtime comunication to the user interface through websockets
+    * frappe-socketio: enables realtime communication to the user interface through websockets
     * frappe-worker-default: background runner
     * frappe-worker-short: background runner for short-running jobs
     * frappe-worker-long: background runner for long-running jobs
     * frappe-schedule
 
-* docker-compose-networks.yml: this yml define the network to comunicate with *Letsencrypt Nginx Proxy Companion*.
+* docker-compose-networks.yml: this yml define the network to communicate with *Letsencrypt Nginx Proxy Companion*.
 
 
 ### Site operations

development/README.md

@@ -8,7 +8,7 @@
 
 ### Bootstrap Containers for development
 
-Clone and change working directory to frappe_docker directory
+Clone and change to frappe_docker directory
 
 ```shell
 git clone https://github.com/frappe/frappe_docker.git
@@ -17,30 +17,34 @@ cd frappe_docker
 
 #### Manually start containers
 
+In case VS Code is not used follow these steps.
+
 ```shell
 docker-compose -f .devcontainer/docker-compose.yml up -d
 ```
 
-Enter the bench container
+Enter the bench container at location `/workspace/development`
 
 ```shell
-docker exec -e "TERM=xterm-256color" -w /workspace/development -it frappe bash
+docker exec -e "TERM=xterm-256color" -w /workspace/development -it devcontainer_frappe_1 bash
 ```
 
-#### Use VSCode Remote Containers extension
+#### Use VS Code Remote Containers extension
 
-- Install Remote Development Pack / Remote Containers extension
+Follow these in case VS Code is used. Do not start containers manually.
-- Install VSCode Python extension
+
-- Open frappe_docker in VSCode
+- Install Remote Development Pack / Remote Containers extension.
-- From Command Palette (Ctrl + Shift + P) Execute Remote Containers : Reopen in Container
+- Install VS Code Python extension.
+- Open frappe_docker in VS Code.
+- From Command Palette (Ctrl + Shift + P) Execute Remote Containers : Reopen in Container.
 
 ### Setup Docker specific bench environment
 
 Notes:
 
-- `development` directory is ignored by it. It is mounted and available in container. Create all your benches inside this directory
+- `development` directory is ignored by git. It is mounted and available in container. Create all your benches inside this directory.
-- Execute these commands from container
+- Execute these commands from container.
-- nvm with node v12 and v10 is installed. Check with `nvm ls`. Node v12 is default
+- nvm with node v12 and v10 is installed. Check with `nvm ls`. Node v12 is default.
 
 #### Setup first bench
 
@@ -62,7 +66,7 @@ bench set-redis-socketio-host redis-socketio:6379
 
 - honcho/Procfile starts processes required for development.
 - By default Procfile has 3 redis processes that it starts. Comment (`#`) or remove these lines and then run `bench start`.
-- Another option is to run following command
+- Another option is to run following command :
 
 ```shell
 honcho start \
@@ -94,15 +98,16 @@ mysql -uroot -p123 -hmariadb
 Execute following queries
 
 ```sql
-UPDATE mysql.user SET Host = '%' where User = 'db_name'; FLUSH PRIVILEGES;
+UPDATE mysql.user SET Host = '%' where User = 'db_name';
-SET PASSWORD FOR 'db_name'@'%' = PASSWORD('db_password'); FLUSH PRIVILEGES;
+SET PASSWORD FOR 'db_name'@'%' = PASSWORD('db_password');
-GRANT ALL PRIVILEGES ON `db_name`.* TO 'db_name'@'%'; FLUSH PRIVILEGES;
+GRANT ALL PRIVILEGES ON `db_name`.* TO 'db_name'@'%';
+FLUSH PRIVILEGES;
 ```
 
 ### Visual Studio Code Python Debugging
 
-- Install VSCode Python Extension once in remote container
+- Install VS Code Python Extension once in remote container
-- Reload VSCode
+- Reload VS Code
 - Do not start `web` process with honcho
 
 ```shell