work in progress

docker/README.md

@@ -27,49 +27,48 @@ In order to make it work, please use the same directories structure as described
 5.1. [Steps](#update-steps)<br/>
 5.2. [Good to know](#good-to-know)
 
-## Preliminary steps
 <a id="preliminary-steps"></a>
+## Preliminary steps
 
-### docker/env file
 <a id="docker-env"></a>
+### docker/env file
 
-Make a copy of the **env.example** and use it as a starting point.
+Make a copy of the **docker/env.example** file and use it as a starting point.
 Set all the environment variables needed by your application. Please refer to the [FabManager README](https://github.com/LaCasemate/fab-manager/blob/master/README.md) for explanations about those variables.
 
-### docker/nginx_with_ssl.conf.example file
 <a id="nginx-conf"></a>
+### docker/nginx_with_ssl.conf.example file
 
 * Replace **MAIN_DOMAIN** (example: fab-manager.com).
 * Replace **URL_WITH_PROTOCOL_HTTPS** (example: https://www.fab-manager.com).
 * Replace **ANOTHER_URL_1**, **ANOTHER_URL_2** (example: .fab-manager.fr)
 
-Side note:
+**Use nginx.conf.example if you don't want SSL for your app.**
-* Use nginx.conf.example if you are not using **SSL**
 
-### setup the server
 <a id="setup-server"></a>
+### setup the server
 
-Go to **DigitalOcean** and create a Droplet with operating system coreOS **stable**.
+Go to [DigitalOcean](https://www.digitalocean.com/) and create a Droplet with operating system coreOS **stable**.
 You need at least 2GB of addressable memory (RAM + swap) to install and use FabManager.
 Choose a datacenter. Set the hostname as your domain name.
 
-### buy a domain name and link it with the droplet
 <a id="buy-domain-link-droplet"></a>
+### buy a domain name and link it with the droplet
 
-1. Buy a domain name on OVH
+1. Buy a domain name on [OVH](https://www.ovh.com/fr/)
 2. Replace the IP address of the domain with the droplet's IP (you can enable the flexible ip and use it)
 3. **Do not** try to access your domain name right away, DNS are not aware of the change yet so **WAIT** and be patient. 
 
-### connect to the droplet via SSH
 <a id="connect-to-droplet"></a>
+### connect to the droplet via SSH
 
 You can already connect to the server with this command: `ssh core@droplet-ip`. When DNS propagation will be done, you will be able to
 connect to the server with `ssh core@your-domain-name`.
 
-### create SWAP file in coreOS
 <a id="create-swap-file"></a>
+### create SWAP file in coreOS
 
-Firstly, switch to sudo and create a swap file
+Switch to sudo and create a swap file:
 
 ```bash
 sudo -i  
@@ -97,7 +96,7 @@ ExecStopPost=/usr/bin/sh -c "/usr/sbin/losetup -d $(/usr/sbin/losetup -j ${SWAPF
 WantedBy=multi-user.target  
 ```
 
-Then add service and start:
+Then enable the service and start it:
 
 ```bash
 systemctl enable /etc/systemd/system/swap.service  
@@ -105,27 +104,32 @@ systemctl start swap
 exit
 ```
 
-### setup folders and env file
 <a id="setup-folders-env-file"></a>
+### setup folders and env file
 
+Create the config folder:
 ```bash
 mkdir -p /home/core/fabmanager/config
 ```
 
-Copy the previously customized `env.example` file as `/home/core/fabmanager/config/env`
+Then, copy the previously customized `env.example` file as `/home/core/fabmanager/config/env`
 
+Create the nginx folder:
 ```bash
 mkdir -p /home/core/fabmanager/config/nginx
 ```
 
+Then,
 Copy the previously customized `nginx_with_ssl.conf.example` as `/home/core/fabmanager/config/nginx/fabmanager.conf`
-OR
-Copy the previously customized `nginx.conf.example` as `/home/core/fabmanager/config/nginx/fabmanager.conf` if you do not want ssl support (not recommended !).
 
-### SSL certificate with LetsEncrypt
+**OR**
+
+Copy the previously customized `nginx.conf.example` as `/home/core/fabmanager/config/nginx/fabmanager.conf` if you do not want to use ssl (not recommended !).
+
 <a id="ssl-certificate-letsencrypt"></a>
+### SSL certificate with LetsEncrypt
 
-*TO BE READ ONLY IF YOU WANT TO USE SSL*.
+**FOLLOW THOSE INSTRUCTIONS ONLY IF YOU WANT TO USE SSL**.
 
 Let's Encrypt is a new Certificate Authority that is free, automated, and open.
 Let’s Encrypt certificates expire after 90 days, so automation of renewing your certificates is important.
@@ -175,8 +179,8 @@ WantedBy=timers.target
 
 That's all for the moment. Keep on with the installation, we'll complete that part after deployment in the [Generate SSL certificate by Letsencrypt](#generate-ssl-cert-letsencrypt).
 
-### Install docker-compose
 <a id="install-docker-compose"></a>
+### Install docker-compose
 
 ```bash
 curl -L https://github.com/docker/compose/releases/download/1.7.1/docker-compose-`uname -s`-`uname -m` > ./docker-compose
@@ -187,18 +191,18 @@ sudo chmod +x /opt/bin/docker-compose
 
 Then copy docker-compose.yml to your app folder `/home/core/fabmanager`.
 
-## Deployment
 <a id="deployment"></a>
+## Deployment
 
-### pull images
 <a id="pull-images"></a>
+### pull images
 
 ```bash
 docker-compose pull
 ```
 
-### setup database
 <a id="setup-database"></a> 
+### setup database
 
 ```bash
 docker-compose run --rm fabmanager bundle exec rake db:create # create the database
@@ -206,23 +210,23 @@ docker-compose run --rm fabmanager bundle exec rake db:migrate # run all the mig
 docker-compose run --rm fabmanager bundle exec rake db:seed # seed the database
 ```
 
-### build assets
 <a id="build-assets"></a>
+### build assets
 
 `docker-compose run --rm fabmanager bundle exec rake assets:precompile`
 
-### prepare Elasticsearch (search engine)
 <a id="prepare-elastic"></a>
+### prepare Elasticsearch (search engine)
 
 `docker-compose run --rm fabmanager bundle exec rake fablab:es_build_stats`
 
-#### start all services
 <a id="start-services"></a>
+#### start all services
 
 `docker-compose up -d`
 
+<a id="generate-ssl-cert-letsencrypt"></a>
 ### Generate SSL certificate by Letsencrypt 
-<a name="generate-ssl-cert-letsencrypt"></a>
 
 **Important: app must be run before starting letsencrypt**
 
@@ -248,8 +252,8 @@ sudo systemctl start letsencrypt.timer
 (check) sudo systemctl list-timers
 ```
 
-## Docker utils
 <a id="docker-utils"></a>
+## Docker utils
 
 ### Restart app
 
@@ -271,38 +275,38 @@ sudo systemctl start letsencrypt.timer
 
 `docker-compose restart`
 
-## Fabmanager update
 <a id="update-fabmanager"></a>
+## Fabmanager update
 
 *This procedure updates fabmanager to the last version by default.*
 
-### Steps
 <a id="update-steps"></a>
+### Steps
 
 
 When a new version is available, this is how to update fabmanager app in a production environment, using docker-compose :
 
-#### go to your app folder
+1. go to your app folder
 
 `cd fabmananger`
 
-#### pull last docker images 
+2. pull last docker images 
 
 `docker-compose pull`
 
-#### stop the app
+3. stop the app
 
 `docker-compose stop fabmanager`
 
-#### remove old assets
+4. remove old assets
 
 `sudo rm -Rf public/assets/`
 
-#### compile new assets
+5. compile new assets
 
 `docker-compose run --rm fabmanager bundle exec rake assets:precompile`
 
-#### run specific commands
+6. run specific commands
 
 Do not forget to check if there are commands to run for your upgrade. Those commands 
 are always specified in the [CHANGELOG](https://github.com/LaCasemate/fab-manager/blob/master/CHANGELOG.md) and prefixed by *[TODO DEPLOY]*. 
@@ -310,7 +314,7 @@ They are also present in the [release pages](https://github.com/LaCasemate/fab-m
 
 They execute specific tasks so they can't be automatic and have to be run by hand.
 
-#### restart all containers
+7. restart all containers
 
 ```bash
   docker-compose down
@@ -319,8 +323,8 @@ They execute specific tasks so they can't be automatic and have to be run by han
 
 You can check that all containers are running with `docker ps`.
 
-### Good to know
 <a id="good-to-know"></a>
+### Good to know
 
 #### Is it possible to update several versions at the same time ?