Docs update

DEVELOPMENT.md

@@ -1,12 +1,12 @@
 # Development
 
-Install instructions in INSTALL.md. Read it before proceeding.
+Install instructions in [[INSTALL.md]]. Read it before proceeding.
 
 ## Basic commands for development
 
-Load env variables (**don't skip this step**):
+Load environment variables (**don't skip this step**):
 
-    source script/env.sh .env .env.development
+    source script/env.sh .env .env.development .env.local .env.development.local
 
 Start development:
 
@@ -14,7 +14,7 @@ Start development:
 
 Build or rebuild:
 
-    docker-compose build`
+    docker-compose build
 
 Debug:
 
@@ -22,10 +22,10 @@ Debug:
 
 To get inside docker web+test containers:
 
-    docker-compose exec -u root development /bin/bash`
+    docker-compose exec -u root development /bin/bash
-    docker-compose exec -u web development /bin/bash`
+    docker-compose exec -u web development /bin/bash
-    docker-compose exec -u root test /bin/bash`
+    docker-compose exec -u root test /bin/bash
-    docker-compose exec -u web test /bin/bash`
+    docker-compose exec -u web test /bin/bash
 
 Restart the web container
 
@@ -34,14 +34,15 @@ Restart the web container
 Run some tests:
 
     docker-compose up --build test
-    docker-compose exec -u web test bundle exec rspec`
+    docker-compose exec -u web test bundle exec rspec
-    docker-compose exec -u web test bundle exec rspec spec/controllers/shoutmsgs_controller_spec.rb`
+    docker-compose exec -u web test bundle exec rspec spec/controllers/shoutmsgs_controller_spec.rb
 
 ## Debugging
 
 Enable debug:
 1. For tests, Make sure ``require 'pry-byebug'`` is uncommented at spec_helper.rb
 1. Uncomment  add `byebug` anywhere
+1. The development console, test command etc. will stop with pry debug options
 
 ## Unresolved issues for development
 
@@ -52,11 +53,15 @@ There are some unresolved issues to setup dev env.
     sudo chown -R 1000:1000 .
     sudo chown -R 999:999 db/data
 
-1. You might have to run migrations manually.
+1. You might have to run db migrations manually.
 
     bundle exec rake db:migrate`
 
-## Tips
+## Unresolved issues in production
+
+1. Be careful when running docker from multiple directories that you do not start eg. database twice
+
+## Development tips
 
 1. If you need to run stuff on your host (eg. ruby, rubocop, bundle install etc) run all commands from the: `Dockerfile`. It should setup identical setup for your machine.
 1. Add docker container names to /etc/hosts. This makes it possible to run test from local machine without using the container since editor/IDE don't integrate with Docker so well.
@@ -68,10 +73,6 @@ There are some unresolved issues to setup dev env.
 1. You can run tests easier if you setup the stuff on your own computer.
 1. Do not commit too much without testing. Also keep commits small for documentation and reversability issues.
 1. You need to rebuild the docker image when you change gems.
-1. To restart NGINX
-
-    docker-compose exec nginx nginx -s
-
 1. To restart PUMA
 
     touch tmp/restart.txt
@@ -82,7 +83,7 @@ Read this to understand design decisions and follow them!
 
 1. Env variables should be used everywhere and loaded from .env* files using Dotenv
   * Load order is in [here]|(https://github.com/bkeepers/dotenv#what-other-env-files-can-i-use)
-  * Local changes go to .env*local and **not** .env
+  * Local changes go to .env*local and **not** .env (unlike previous versions)
   * Passwords are in ENV variables for now so they don't have to duplicated between DB and Rails.
 1. Everything should be running on containers.
   * Docker-compose is the heart of deployment
@@ -106,6 +107,17 @@ Read this to understand design decisions and follow them!
 * ``OBSOLETE`` remove this at some point
 * ``DEBUG`` uncomment following lines to enable debug
 
+## Assets and state data
+
+1. Currently the following state data exists:
+  * `log` has all Rails and Rails submodule log files
+  * `db/data` has SQL database
+  * `tmp` has temporary data like sockets, pids, cache etc. not in git repo index
+  * `public` has all public data on website like images etc.
+    * `public/local` has avatars etc. user uploaded content and is not in git repo index
+    * `public/assets` is auto-generated by Rails on precompile and is not in git repo index
+    * `public/files` is stored elsewhere and aliased by nginx, also not in git repo index
+
 ## TODO issues for dev
 
 1. Puma should be running (eg. spring), and if debugger is used it should be able to connect via docker-compose up