Update documentation

3 files changed, 79 insertions, 2 deletions

diff --git a/doc/docker/using_docker_images.md b/doc/docker/using_docker_images.md
index a88bb62..ef449cd 100644
--- a/doc/docker/using_docker_images.md
+++ b/doc/docker/using_docker_images.md
@@ -66,6 +66,39 @@ Alias hostname for the service is made from the image name:
 1. Everything after `:` is stripped,
 2. '/' is replaced to `_`.
 
+### Configuring services
+Many services accept environment variables, which allow you to easily change database names or set account names depending on the environment.
+
+GitLab Runner 0.5.0 and up passes all YAML-defined variables to created service containers.
+
+1. To configure database name for [postgres](https://registry.hub.docker.com/u/library/postgres/) service,
+you need to set POSTGRES_DB.
+
+    ```yaml
+    services:
+    - postgres
+    
+    variables:
+      POSTGRES_DB: gitlab
+    ```
+
+1. To use [mysql](https://registry.hub.docker.com/u/library/mysql/) service with empty password for time of build, 
+you need to set MYSQL_ALLOW_EMPTY_PASSWORD.
+
+    ```yaml
+    services:
+    - mysql
+    
+    variables:
+      MYSQL_ALLOW_EMPTY_PASSWORD: yes
+    ```
+
+For other possible configuration variables check the 
+https://registry.hub.docker.com/u/library/mysql/ or https://registry.hub.docker.com/u/library/postgres/
+or README page for any other Docker image.
+
+**Note: All variables will passed to all service containers. It's not designed to distinguish which variable should go where.**
+
 ### 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
diff --git a/doc/variables/README.md b/doc/variables/README.md
index d61474a..04c6bf1 100644
--- a/doc/variables/README.md
+++ b/doc/variables/README.md
@@ -1,6 +1,17 @@
 ## Variables
 When receiving a build from GitLab CI, the runner prepares the build environment.
-It starts by setting a list of **predefined variables** (Environment Variables) and a list of **user-defined variables** (Secure Variables)
+It starts by setting a list of **predefined variables** (Environment Variables) and a list of **user-defined variables**
+
+The variables can be overwritten. They take precedence over each other in this order:
+1. Secure variables
+1. YAML-defined variables
+1. Predefined variables
+
+For example, if you define:
+1. API_TOKEN=SECURE as Secure Variable
+1. API_TOKEN=YAML as YAML-defined variable
+
+The API_TOKEN will take the Secure Variable value: `SECURE`.
 
 ### Predefined variables (Environment Variables)
 
@@ -36,8 +47,25 @@ export CI_SERVER_REVISION=""
 export CI_SERVER_VERSION=""
 ```
 
+### YAML-defined variables
+**This feature requires GitLab Runner 0.5.0 or higher**
+
+GitLab CI allows you to add to `.gitlab-ci.yml` variables that are set in build environment.
+The variables are stored in repository and are meant to store non-sensitive project configuration, ie. RAILS_ENV or DATABASE_URL.
+
+```yaml
+variables:
+  DATABASE_URL: "postgres://postgres@postgres/my_database"
+```
+
+These variables can be later used in all executed commands and scripts.
+
+The YAML-defined variables are also set to all created service containers, thus allowing to fine tune them.
+
+More information about Docker integration can be found in [Using Docker Images](../docker/using_docker_images.md).
+
 ### User-defined variables (Secure Variables)
-**This feature requires `gitlab-runner` with version equal or greater than 0.4.0.**
+**This feature requires GitLab Runner 0.4.0 or higher**
 
 GitLab CI allows you to define per-project **Secure Variables** that are set in build environment. 
 The secure variables are stored out of the repository (the `.gitlab-ci.yml`).
diff --git a/doc/yaml/README.md b/doc/yaml/README.md
index 301144a..4caecca 100644
--- a/doc/yaml/README.md
+++ b/doc/yaml/README.md
@@ -55,6 +55,7 @@ There are a few `keywords` that can't be used as job names:
 | stages        | optional | Define build stages |
 | types         | optional | Alias for `stages` |
 | before_script | optional | Define commands prepended for each job's script |
+| variables     | optional | Define build variables |
 
 ### image and services
 This allows to specify a custom Docker image and a list of services that can be used for time of the build.
@@ -94,6 +95,21 @@ There are also two edge cases worth mentioning:
 ### types
 Alias for [stages](#stages).
 
+### variables
+**This feature requires `gitlab-runner` with version equal or greater than 0.5.0.**
+
+GitLab CI allows you to add to `.gitlab-ci.yml` variables that are set in build environment.
+The variables are stored in repository and are meant to store non-sensitive project configuration, ie. RAILS_ENV or DATABASE_URL.
+
+```yaml
+variables:
+  DATABASE_URL: "postgres://postgres@postgres/my_database"
+```
+
+These variables can be later used in all executed commands and scripts.
+
+The YAML-defined variables are also set to all created service containers, thus allowing to fine tune them.
+
 ## Jobs
 `.gitlab-ci.yml` allows you to specify an unlimited number of jobs.
 Each job has to have a unique `job_name`, which is not one of the keywords mentioned above.