advanced-configuration.md 6.98 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
Configuration uses the TOML format as described here: <https://github.com/toml-lang/toml>.
The file to be edited can be found in `/home/gitlab_ci_multi_runner/config.toml`.

### The global section

This defines global settings of multi-runner.

| Setting | Explanation |
| ------- | ----------- |
| `concurrent` | limits how many jobs globally can be run concurrently. The most upper limit of jobs using all defined runners |

Example:

```bash
concurrent = 4
```

### The [[runners]] section

This defines one runner entry.

| Setting | Explanation |
| ------- | ----------- |
| `name`              | not used, just informatory |
| `url`               | CI URL |
| `token`             | runner token |
| `limit`             | limit how many jobs can be handled concurrently by this token. 0 simply means don't limit |
| `executor`          | select how a project should be built, see next section |
29
| `shell`             | the name of shell to generate the script (default value is platform dependent) |
30 31
| `builds_dir`        | directory where builds will be stored in context of selected executor (Locally, Docker, SSH) |
| `environment`       | append or overwrite environment variables |
32
| `disable_verbose`   | don't print run commands |
33
| `output_limit`      | set maximum build log size in kilobytes, by default set to 4096 (4MB) |
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86

Example:

```bash
[[runners]]
  name = "ruby-2.1-docker"
  url = "https://CI/"
  token = "TOKEN"
  limit = 0
  executor = "docker"
  builds_dir = ""
  shell = ""
  environment = ["ENV=value", "LC_ALL=en_US.UTF-8"]
  disable_verbose = false
```

### The EXECUTORS

There are a couple of available executors currently.

| Executor | Explanation |
| -------- | ----------- |
| `shell`       | run build locally, default |
| `docker`      | run build using Docker container - this requires the presence of `[runners.docker]` |
| `docker-ssh`  | run build using Docker container, but connect to it with SSH - this requires the presence of `[runners.docker]` and `[runners.ssh]` |
| `ssh`         | run build remotely with SSH - this requires the presence of `[runners.ssh]` |
| `parallels`   | run build using Parallels VM, but connect to it with SSH - this requires the presence of `[runners.parallels]` and `[runners.ssh]` |

### The SHELLS

There are a couple of available shells that can be run on different platforms.

| Shell | Explanation |
| ----- | ----------- |
| `bash`        | generate Bash (Bourne-shell) script. All commands executed in Bash context (default for all Unix systems) |
| `cmd`         | generate Windows Batch script. All commands are executed in Batch context (default for Windows) |
| `powershell`  | generate Windows PowerShell script. All commands are executed in PowerShell context |

### The [runners.docker] section

This defines the Docker Container parameters.

| Parameter | Explanation |
| --------- | ----------- |
| `host`                      | specify custom Docker endpoint, by default `DOCKER_HOST` environment is used or `unix:///var/run/docker.sock` |
| `hostname`                  | specify custom hostname for Docker container |
| `tls_cert_path`             | when set it will use `ca.pem`, `cert.pem` and `key.pem` from that folder to make secure TLS connection to Docker (useful in boot2docker) |
| `image`                     | use this image to run builds |
| `privileged`                | make container run in Privileged mode (insecure) |
| `disable_cache`             | disable automatic |
| `wait_for_services_timeout` | specify how long to wait for docker services, set to 0 to disable, default: 30 |
| `cache_dir`                 | specify where Docker caches should be stored (this can be absolute or relative to current working directory) |
| `registry`                  | specify custom Docker registry to be used |
rockyluke's avatar
rockyluke committed
87
| `volumes`                   | specify additional volumes that should be mounted (same syntax as Docker -v option) |
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110
| `extra_hosts`               | specify hosts that should be defined in container environment |
| `links`                     | specify containers which should be linked with building container |
| `services`                  | specify additional services that should be run with build. Please visit [Docker Registry](https://registry.hub.docker.com/) for list of available applications. Each service will be run in separate container and linked to the build. |

Example:

```bash
[runners.docker]
  host = ""
  hostname = ""
  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
  image = "ruby:2.1"
  privileged = false
  disable_cache = false
  wait_for_services_timeout = 30
  cache_dir = ""
  registry = ""
  volumes = ["/data", "/home/project/cache"]
  extra_hosts = ["other-host:127.0.0.1"]
  links = ["mysql_container:mysql"]
  services = ["mysql", "redis:2.8", "postgres:9"]
```

rockyluke's avatar
rockyluke committed
111 112 113 114 115 116
#### Volumes in the [runners.docker] section

You can find the complete guide of Docker volume usage [here](https://docs.docker.com/userguide/dockervolumes/).

Let's use some examples to explain how it work (we assume we have a working runners).

rockyluke's avatar
rockyluke committed
117
##### Example 1: adding a data volume
rockyluke's avatar
rockyluke committed
118 119

A data volume is a specially-designated directory within one or more containers that bypasses the Union File System. Data volumes are designed to persist data, independent of the container's life cycle.
rockyluke's avatar
rockyluke committed
120 121

```bash
rockyluke's avatar
rockyluke committed
122 123 124 125 126 127 128 129 130
[runners.docker]
  host = ""
  hostname = ""
  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
  image = "ruby:2.1"
  privileged = false
  disable_cache = true
  volumes = ["/path/to/volume/in/container"]
```
rockyluke's avatar
rockyluke committed
131

rockyluke's avatar
rockyluke committed
132 133
This will create a new volume inside the container at /path/to/volume/in/container.

rockyluke's avatar
rockyluke committed
134
##### Example 2: mount a host directory as a data volume
rockyluke's avatar
rockyluke committed
135 136 137 138

In addition to creating a volume using you can also mount a directory from your Docker daemon's host into a container. It's usefull when you want to store builds outside the container.

```bash
rockyluke's avatar
rockyluke committed
139 140 141 142 143 144 145
[runners.docker]
  host = ""
  hostname = ""
  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
  image = "ruby:2.1"
  privileged = false
  disable_cache = true
rockyluke's avatar
rockyluke committed
146
  volumes = ["/path/to/bind/from/host:/path/to/bind/in/container:rw"]
rockyluke's avatar
rockyluke committed
147 148
```

rockyluke's avatar
rockyluke committed
149 150
This will use /path/to/bind/from/host of the CI host inside the container at /path/to/bind/in/container.

151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189
### The [runners.parallels] section

This defines the Parallels parameters.

| Parameter | Explanation |
| --------- | ----------- |
| `base_name`         | name of Parallels VM which will be cloned |
| `template_name`     | custom name of Parallels VM linked template (optional) |
| `disable_snapshots` | if disabled the VMs will be destroyed after build |

Example:

```bash
[runners.parallels]
  base_name = "my-parallels-image"
  template_name = ""
  disable_snapshots = false
```

### The [runners.ssh] section

This defines the SSH connection parameters.

| Parameter  | Explanation |
| ---------- | ----------- |
| `host`     | where to connect (overriden when using `docker-ssh`) |
| `port`     | specify port, default: 22 |
| `user`     | specify user |
| `password` | specify password |

Example:

```
[runners.ssh]
  host = "my-production-server"
  port = "22"
  user = "root"
  password = "production-server-password"
```