Rewrite Development Readme so it's idiotproof

development/README.md

@@ -6,54 +6,46 @@
 - docker-compose
 - user added to docker group
 
-### Bootstrap Containers for development
+## Bootstrap Containers for development
 
-Clone and change to frappe_docker directory
+Clone and change directory to frappe_docker directory
 
 ```shell
 git clone https://github.com/frappe/frappe_docker.git
 cd frappe_docker
 ```
 
-#### Manually start containers
+## Use VSCode Remote Containers extension
 
-In case VS Code is not used follow these steps.
+For most people getting started with Frappe development, the best solution is to use [ VSCode Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
 
-```shell
+- Install Remote - Containers for VSCode
-docker-compose -f .devcontainer/docker-compose.yml up -d
+    - through command line `code --install-extension ms-vscode-remote.remote-containers`
-```
+    - clicking on the following link: [install](vscode:extension/ms-vscode-remote.remote-containers)
-
+- Install Python for VSCode
-Enter the bench container at location `/workspace/development`
+    - through command line `code --install-extension ms-python.python`
-
+    - clicking on the following link: [install](vscode:extension/ms-python.python)
-```shell
+- Open frappe_docker folder in VS Code.
-docker exec -e "TERM=xterm-256color" -w /workspace/development -it devcontainer_frappe_1 bash
+    - `code .`
-```
+- From Command Palette (Ctrl + Shift + P) Execute Remote Containers : Reopen in Container. You can also click in the bottom left corner to access the remote container menu.
-
-#### Use VS Code Remote Containers extension
-
-Follow these in case VS Code is used. Do not start containers manually.
-
-- Install Remote Development Pack / Remote Containers extension.
-- 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 git. It is mounted and available in container. Create all your benches inside this directory.
+- The `development` directory is ignored by git. It is mounted and available inside the container. Create all your benches (installations of bench, the tool that manages frappe) inside this directory.
-- Execute these commands from container.
 - nvm with node v12 and v10 is installed. Check with `nvm ls`. Node v12 is default.
 
-#### Setup first bench
+### Setup first bench
+
+Run the following commands in the terminal inside the container. You might need to create a new terminal in VSCode.
 
 ```shell
 bench init --skip-redis-config-generation --frappe-branch version-12 frappe-bench
 cd frappe-bench
 ```
 
-#### Set hosts
+### Setup hosts
+
+We need to tell bench to use the right containers instead of localhosts. Run the following commands inside the container:
 
 ```shell
 bench set-mariadb-host mariadb
@@ -62,52 +54,91 @@ bench set-redis-queue-host redis-queue:6379
 bench set-redis-socketio-host redis-socketio:6379
 ```
 
-#### Changes related to bench start / honcho / Procfile
+### Edit Honcho's Procfile
 
-- honcho/Procfile starts processes required for development.
+Honcho is the tool used by Bench to manage all the processes Frappe requires. Usually, these all run in localhost, but in this case we have external containers for Redis. For this reason, we have to stop Honcho from trying to start Redis processes.
-- 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 :
+Open the Procfile file and remove the three lines containing the configuration from Redis, either by editing manually the file
 
 ```shell
-honcho start \
+code Procfile
-    web \
-    socketio \
-    watch \
-    schedule \
-    worker_short \
-    worker_long \
-    worker_default
 ```
 
-#### Changes related to MariaDB
+or running the following command:
+```shell
+sed -i '/redis/d' ./Procfile
+```
 
-Notes:
+### Create a new site with bench
 
-- `bench new-site` command creates a user in mariadb with container IP as host
+You can create a new site with the following command
-- After rebuilding container there is a chance that new bench container will not be able to access mariadb
-- `'db_name'@'%'` needs to be set in mariadb and permission to the site database be given to the user
-- Replace `db_name` and `db_password` from site's `site_config.json`
-- MariaDB root password is 123
 
-Enter mariadb shell
+```shell
+bench new-site sitename
+```
+
+for example:
+
+```shell
+bench new-site localhost
+```
+
+The command will ask the MariaDB root password. The default root password is `123`
+Your website will now be accessible on [localhost on port 8000](http://locahost:8000)
+
+### Fixing MariaDB issues after rebuilding the container
+
+The `bench new-site` command creates a user in MariaDB with container IP as host, for this reason after rebuilding the container there is a chance that you will not be able to access MariaDB correctly with the previous configuration
+The parameter `'db_name'@'%'` needs to be set in MariaDB and permission to the site database properly assigned to the user.
+
+Open sites/common_site_config.json:
+
+
+```shell
+code sites/common_site_config.json
+```
+
+and take note of the parameters `db_name` and `db_password`.
+
+Enter MariaDB Interactive shell:
 
 ```shell
 mysql -uroot -p123 -hmariadb
 ```
 
-Execute following queries
+Execute following queries replacing db_name` and `db_password` with the values found in common_site_config.json.
 
 ```sql
 UPDATE mysql.user SET Host = '%' where User = 'db_name'; FLUSH PRIVILEGES;
 SET PASSWORD FOR 'db_name'@'%' = PASSWORD('db_password'); FLUSH PRIVILEGES;
 GRANT ALL PRIVILEGES ON `db_name`.* TO 'db_name'@'%'; FLUSH PRIVILEGES;
+EXIT;
+```
+
+## Manually start containers
+
+In case you don't use VSCode, you may start the containers manually with the following command:
+
+```shell
+docker-compose -f .devcontainer/docker-compose.yml up -d
+```
+
+And enter the interactive shell for the development container with the following command:
+
+```shell
+docker exec -e "TERM=xterm-256color" -w /workspace/development -it devcontainer_frappe_1 bash
 ```
 
 ### Visual Studio Code Python Debugging
 
-- Install VS Code Python Extension once in remote container
+To enable Python debugging inside Visual Studio Code, you must first install the `ms-python.python` extension inside the container.
-- Reload VS Code
+
-- Do not start `web` process with honcho
+- Click on the extensions icon of VSCode
+- Search `ms-python.python`
+- Click on `Install on Dev Container: Frappe Bench`
+- Click on 'Reload'
+
+We need to start bench separately through the VSCode debugger. For this reason, **instead** of running `bench start` you should run the following command inside the frappe-bench directory:
 
 ```shell
 honcho start \
@@ -119,4 +150,4 @@ honcho start \
     worker_default
 ```
 
-- On debugger tab, Connect debugger. This will start the web process with debugger connected
+This command starts all processes but Redis (which is already running in separate container) and the `web` process, which we can finally start from the debugger tab of VSCode.