Docker usage

1 files changed, 45 insertions, 18 deletions

diff --git a/doc/builds_configuration/docker.md b/doc/builds_configuration/docker.md
index 0d64431..6d693d1 100644
--- a/doc/builds_configuration/docker.md
+++ b/doc/builds_configuration/docker.md
@@ -1,10 +1,18 @@
-## Use Docker to build your projects
-GitLab-CI allows to use Docker containers to build projects. `gitlab-runner` when installed on server with `Docker Engine` creates a new build container for each build. It makes it easier to have reproducible build environment, but also to easily replay all build steps on workstation.
+# Docker integration
+GitLab CI can use [Docker Engine](https://www.docker.com/) to build projects. 
+
+Docker is an open-source project that allows to use predefined images to run applications 
+in independent "containers" that are run within a single Linux instance. 
+[Docker Hub](https://registry.hub.docker.com/) have rich database of  built images that can be used to build applications.
+
+Docker when used with GitLab CI runs each build in separate and isolated container using predefined image and always from scratch.
+It makes it easier to have simple and reproducible build environment that can also be run on your workstation.
+This allows you to test all commands from your shell, rather than having to test them on a CI server.
 
 ### Register Docker runner
-To use `gitlab-runner` with `Docker` you need to register `runner` with `docker` executor:
+To use GitLab Runner with Docker you need to register new runner to use `docker` executor:
 
-```
+```bash
 gitlab-ci-multi-runner register \
   --url "https://ci.gitlab.com/" \
   --registration-token "PROJECT_REGISTRATION_TOKEN" \
@@ -15,40 +23,53 @@ gitlab-ci-multi-runner register \
   --docker-mysql latest
 ```
 
-The above example will create a new runner that uses `docker` executor. To build projects it will use `ruby:2.1` image and will allow to access `postgres` and `mysql` databases for time of the build.
+The registered runner will use `ruby:2.1` image and will allow to access `postgres` and `mysql` databases for time of the build.
 
 ### What is image?
-The image is the name of any repository that is present in local Docker Engine or any repository that can be found at [Docker Hub](https://registry.hub.docker.com/). If you still don't know what it is, please read the [Docker Fundamentals](https://docs.docker.com/introduction/understanding-docker/).
+The image is the name of any repository that is present in local Docker Engine or any repository that can be found at [Docker Hub](https://registry.hub.docker.com/). 
+For more information about the image and Docker Hub please read the [Docker Fundamentals](https://docs.docker.com/introduction/understanding-docker/).
 
 ### What is service?
-Service is just another image that is run for time of your build and is linked to your build. This allows you to access the service image during build time. The service image can run any application, but most common use case is to run some database container, ie.: `mysql`. It's easier and faster to use existing image, run it as additional container than install `mysql` on your build container every time.
+Service is just another image that is run for time of your build and is linked to your build. This allows you to access the service image during build time. 
+The service image can run any application, but most common use case is to run some database container, ie.: `mysql`. 
+It's easier and faster to use existing image, run it as additional container than install `mysql` every time project is built.
 
 #### How is service linked to the build?
-There's good document that describes how `docker` linking works: [Linking containers together](https://docs.docker.com/userguide/dockerlinks/). To summarize: if you add `mysql` as service to your application, this image will be used to create container that is linked to build container. The service container for MySQL will be accessible under hostname `mysql`. So, **to access your database service you have to connect to host: `mysql` instead of socket or `localhost`**.
+There's good document that describes how Docker linking works: [Linking containers together](https://docs.docker.com/userguide/dockerlinks/). 
+To summarize: if you add `mysql` as service to your application, the image will be used to create container that is linked to build container. 
+The service container for MySQL will be accessible under hostname `mysql`.
+So, **to access your database service you have to connect to host: `mysql` instead of socket or `localhost`**.
 
 ### How to use other images as services?
-You are not limited to have only database services. You can hand modify `config.toml` to add any image as service found at [Docker Hub](https://registry.hub.docker.com/). Look for `[runners.docker]` section:
+You are not limited to have only database services. 
+You can hand modify `config.toml` to add any image as service found at [Docker Hub](https://registry.hub.docker.com/). 
+Look for `[runners.docker]` section:
 ```
 [runners.docker]
   image = "ruby:2.1"
   services = ["mysql:latest", "postgres:latest"]
 ```
 
-For example you need `wordpress` instance to test some API integration with `Wordpress`. You can for example use this image: [tutum/wordpress](https://registry.hub.docker.com/u/tutum/wordpress/). This is image that have fully preconfigured `wordpress` and have `MySQL` server built-in:
+For example you need `wordpress` instance to test some API integration with `Wordpress`. 
+You can for example use this image: [tutum/wordpress](https://registry.hub.docker.com/u/tutum/wordpress/). 
+This is image that have fully preconfigured `wordpress` and have `MySQL` server built-in:
 ```
 [runners.docker]
   image = "ruby:2.1"
   services = ["mysql:latest", "postgres:latest", "tutum/wordpress:latest"]
 ```
 
-Next time when you run your application the `tutum/wordpress` will be started and you will have access to it from your build container under hostname: `tutum_wordpress`.
+Next time when you run your application the `tutum/wordpress` will be started 
+and you will have access to it from your build container under hostname: `tutum_wordpress`.
 
 Alias hostname for the service is made from the image name:
 1. Everything after `:` is stripped,
 2. '/' is replaced to `_`.
 
 ### Overwrite image and services
-It's possible to overwrite `docker-image` and specify services from `.gitlab-ci.yml`. If you add at the top of your `.gitlab-ci.yml` `image` and `services` the `Docker` executor will use the values defined in YAML instead of the ones that were specified during runner's registration.
+It's possible to overwrite `docker-image` and specify services from `.gitlab-ci.yml`.
+If you add to your YAML the `image` and the `services` these parameters
+be used instead of the ones that were specified during runner's registration.
 ```
 image: ruby:2.2
 services:
@@ -61,7 +82,7 @@ test:
   - bundle exec rake spec
 ```
 
-It's also possible to define image and service for specific job:
+It's possible to define image and service per-job:
 ```
 before_install:
   - bundle install
@@ -81,17 +102,22 @@ test:2.2:
   - bundle exec rake spec
 ```
 
-#### How to enable overwritting?
-To have that feature working you have to **enable it first** (it's disabled by default for security reasons). You can do that by hand modyfing runner configuration: `config.toml`. Please go to section where is `[runners.docker]` definition for your runner. Add `allowed_images` and `allowed_services` to specify what images are allowed to be picked from `.gitlab-ci.yml`:
+#### How to enable overwriting?
+To enable overwriting you have to **enable it first** (it's disabled by default for security reasons). 
+You can do that by hand modifying runner configuration: `config.toml`. 
+Please go to section where is `[runners.docker]` definition for your runner. 
+Add `allowed_images` and `allowed_services` to specify what images are allowed to be picked from `.gitlab-ci.yml`:
 ```
 [runners.docker]
   image = "ruby:2.1"
   allowed_images = ["ruby:*", "python:*"]
   allowed_services = ["mysql:*", "redis:*"]
 ```
-This enables you to use in your `.gitlab-ci.yml` any image that matches above wildcards. You will be able to pick any `ruby` and `python` version, but not any other image. The same apply for services. 
+This enables you to use in your `.gitlab-ci.yml` any image that matches above wildcards. 
+You will be able to pick only `ruby` and `python` images. 
+The same rule can be applied to limit services. 
 
-If you are courageous enough, because you run it for your personal or trusted projects, you can make it fully open and accept everything:
+If you are courageous enough, you can make it fully open and accept everything:
 ```
 [runners.docker]
   image = "ruby:2.1"
@@ -132,4 +158,5 @@ $ make <- or any other build step
 ```
 docker rm -f -v build build-mysql build-postgres
 ```
-This will forcefully (the `-f` switch) remove build container and service containers and all volumes (the `-v` switch) that were created with the container creation.
+This will forcefully (the `-f` switch) remove build container and service containers 
+and all volumes (the `-v` switch) that were created with the container creation.