From ef201e6fcf8ac4e2084eafeee5427ed7d47787f2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Garc=C3=ADa=20Aubert?=
 <danielgarciaaubert@gmail.com>
Date: Fri, 29 Nov 2019 16:30:48 +0100
Subject: [PATCH] Improve docker section in docs

---
 README.md           | 17 ++++++++++++-----
 docker/reference.md | 38 ++++++++++++++++++++++++--------------
 2 files changed, 36 insertions(+), 19 deletions(-)

diff --git a/README.md b/README.md
index 3451fe59..a3dc81cb 100644
--- a/README.md
+++ b/README.md
@@ -74,18 +74,25 @@ We provide docker images just for testing and continuous integration purposes:
 * [`nodejs-xenial-pg1121`](https://hub.docker.com/r/carto/nodejs-xenial-pg1121/tags)
 * [`nodejs-xenial-pg101`](https://hub.docker.com/r/carto/nodejs-xenial-pg101/tags)
 
-And useful `npm` scripts:
+You can find instructions to install Docker, download, and update images [here](https://github.com/CartoDB/Windshaft-cartodb/blob/master/docker/reference.md).
 
-* Run test in a docker image with a specific Node.js version:
+### Useful `npm` scripts
+
+Run test in a docker image with a specific Node.js version:
 
 ```shell
-$ DOCKER_IMAGE=carto/nodejs-xenial-pg1121:latest NODE_VERSION=10.15.1 npm run test:docker
+$ DOCKER_IMAGE=<docker-image-tag> NODE_VERSION=<nodejs-version> npm run test:docker
 ```
 
-* In case you need to debug:
+Where:
+
+* `<docker-image-tag>`: the tag of required docker image, e.g. `carto/nodejs-xenial-pg1121:latest`
+* `<nodejs-version>`: the Node.js version, e.g. `10.15.1`
+
+In case you need to debug:
 
 ```shell
-$ DOCKER_IMAGE=carto/nodejs-xenial-pg1121:latest npm run docker:bash
+$ DOCKER_IMAGE=<docker-image-tag> npm run docker:bash
 ```
 
 ## Documentation
diff --git a/docker/reference.md b/docker/reference.md
index 31dd26cb..601afe17 100644
--- a/docker/reference.md
+++ b/docker/reference.md
@@ -1,23 +1,33 @@
-After running the tests with docker, you will need Docker installed and the docker image downloaded.
+# Testing with Docker
+
+Before running the tests with docker, you'll need Docker installed and the docker image downloaded.
 
 ## Install docker
-`sudo apt install docker.io && sudo usermod -aG docker $(whoami)`
+
+```shell
+$ sudo apt install docker.io && sudo usermod -aG docker $(whoami)
+```
 
 ## Download image
-`docker pull carto/IMAGE`
+
+```shell
+docker pull carto/IMAGE
+```
 
 ## Carto account
-https://hub.docker.com/r/carto/
+
+* `https://hub.docker.com/r/carto/`
 
 ## Update image
-- Edit the docker image file with your desired changes
-- Build image:
-  - `docker build -t carto/IMAGE -f docker/DOCKER_FILE docker/`
 
-- Upload to docker hub:
-  - Login into docker hub:
-    - `docker login`
-  - Create tag:
-    - `docker tag carto/IMAGE carto/IMAGE`
-  - Upload:
-    - `docker push carto/IMAGE`
+* Edit the docker image file with your desired changes
+* Build image:
+  * `docker build -t carto/IMAGE -f docker/DOCKER_FILE docker/`
+
+* Upload to docker hub:
+  * Login into docker hub:
+    * `docker login`
+  * Create tag:
+    * `docker tag carto/IMAGE carto/IMAGE`
+  * Upload:
+    * `docker push carto/IMAGE`