Merge branch 'docker-doc' into 'master'

Added information about building projects using Docker

/cc @JobV

See merge request !178

1 files changed, 162 insertions, 0 deletions

diff --git a/doc/builds_configuration/docker.md b/doc/builds_configuration/docker.md
new file mode 100644
index 0000000..1ee7d10
--- /dev/null
+++ b/doc/builds_configuration/docker.md
@@ -0,0 +1,162 @@
+# 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 new runner to use `docker` executor:
+
+```bash
+gitlab-ci-multi-runner register \
+  --url "https://ci.gitlab.com/" \
+  --registration-token "PROJECT_REGISTRATION_TOKEN" \
+  --description "docker-ruby-2.1" \
+  --executor "docker" \
+  --docker-image ruby:2.1 \
+  --docker-postgres latest \
+  --docker-mysql latest
+```
+
+**The registered runner will use `ruby:2.1` image and will run two services (`postgres:latest` and `mysql:latest`) that will be accessible 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/). 
+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` 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, 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:
+```
+[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:
+```
+[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`.
+
+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 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:
+  - postgres:9.3
+before_install:
+  - bundle install
+  
+test:
+  script:
+  - bundle exec rake spec
+```
+
+It's possible to define image and service per-job:
+```
+before_install:
+  - bundle install
+
+test:2.1:
+  image: ruby:2.1
+  services:
+  - postgres:9.3
+  script:
+  - bundle exec rake spec
+
+test:2.2:
+  image: ruby:2.2
+  services:
+  - postgres:9.4
+  script:
+  - bundle exec rake spec
+```
+
+#### 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 only `ruby` and `python` images. 
+The same rule can be applied to limit services. 
+
+If you are courageous enough, you can make it fully open and accept everything:
+```
+[runners.docker]
+  image = "ruby:2.1"
+  allowed_images = ["*"]
+  allowed_services = ["*"]
+```
+
+**It the feature is not enabled, or image isn't allowed the error message will be put into the build log.**
+
+### How it works?
+1. Create any service container: `mysql`, `postgresql`, `mongodb`, `redis`.
+1. Create cache container to store all volumes as defined in `config.toml` and `Dockerfile` of build image (`ruby:2.1` as in above example).
+1. Create build container and link any service container to build container.
+1. Start build container and send build script to the container.
+1. Run build script.
+1. Checkout code in: `/builds/group-name/project-name/`.
+1. Run any step defined in `.gitlab-ci.yml`.
+1. Check exit status of build script.
+1. Remove build container and all created service containers.
+
+### How to debug build locally?
+1. Create build environment locally first using following commands:
+```
+$ docker run -d -n build-mysql mysql:latest
+$ docker run -d -n build-postgres postgres:latest
+$ docker run -n build -it -l mysql:build-mysql -l postgres:build-postgres ruby:2.1 /bin/bash
+```
+This will create two service containers (MySQL and PostgreSQL) that are linked to build container created as a last one.
+
+1. Then in context of docker container you can copy-paste your build script:
+```
+$ git clone https://gitlab.com/gitlab-org/gitlab-ci-multi-runner.git /builds/gitlab-org/gitlab-ci-multi-runner
+$ cd /builds/gitlab-org/gitlab-ci-multi-runner
+$ make <- or any other build step
+```
+
+1. At the end remove all containers:
+```
+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.