Commit a2c615d1 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Merge branch 'tm/docs/docker-extended-entrypoint-fix' into 'master'

Fix entrypoint overriding documentation

See merge request gitlab-org/gitlab-ce!15884
parents 8d691856 9f3df649
...@@ -319,45 +319,62 @@ As you can see, the syntax of `command` is similar to [Dockerfile's `CMD`][cmd]. ...@@ -319,45 +319,62 @@ As you can see, the syntax of `command` is similar to [Dockerfile's `CMD`][cmd].
> Introduced in GitLab and GitLab Runner 9.4. Read more about the [extended > Introduced in GitLab and GitLab Runner 9.4. Read more about the [extended
configuration options](#extended-docker-configuration-options). configuration options](#extended-docker-configuration-options).
Before showing the available entrypoint override methods, let's describe shortly
how the Runner starts and uses a Docker image for the containers used in the
CI jobs:
1. The Runner starts a Docker container using the defined entrypoint (default
from `Dockerfile` that may be overridden in `.gitlab-ci.yml`)
1. The Runner attaches itself to a running container.
1. The Runner prepares a script (the combination of
[`before_script`](../yaml/README.md#before_script),
[`script`](../yaml/README.md#script),
and [`after_script`](../yaml/README.md#after_script)).
1. The Runner sends the script to the container's shell STDIN and receives the
output.
To override the entrypoint of a Docker image, the recommended solution is to
define an empty `entrypoint` in `.gitlab-ci.yml`, so the Runner doesn't start
a useless shell layer. However, that will not work for all Docker versions, and
you should check which one your Runner is using. Specifically:
- If Docker 17.06 or later is used, the `entrypoint` can be set to an empty value.
- If Docker 17.03 or previous versions are used, the `entrypoint` can be set to
`/bin/sh -c`, `/bin/bash -c` or an equivalent shell available in the image.
The syntax of `image:entrypoint` is similar to [Dockerfile's `ENTRYPOINT`][entrypoint].
----
Let's assume you have a `super/sql:experimental` image with some SQL database Let's assume you have a `super/sql:experimental` image with some SQL database
inside it and you would like to use it as a base image for your job because you inside it and you would like to use it as a base image for your job because you
want to execute some tests with this database binary. Let's also assume that want to execute some tests with this database binary. Let's also assume that
this image is configured with `/usr/bin/super-sql run` as an entrypoint. That this image is configured with `/usr/bin/super-sql run` as an entrypoint. That
means, that when starting the container without additional options, it will run means that when starting the container without additional options, it will run
the database's process, while Runner expects that the image will have no the database's process, while Runner expects that the image will have no
entrypoint or at least will start with a shell as its entrypoint. entrypoint or that the entrypoint is prepared to start a shell command.
Before the new extended Docker configuration options, you would need to create
your own image based on the `super/sql:experimental` image, set the entrypoint
to a shell and then use it in job's configuration, like:
```Dockerfile With the extended Docker configuration options, instead of creating your
# my-super-sql:experimental image's Dockerfile own image based on `super/sql:experimental`, setting the `ENTRYPOINT`
to a shell, and then using the new image in your CI job, you can now simply
define an `entrypoint` in `.gitlab-ci.yml`.
FROM super/sql:experimental **For Docker 17.06+:**
ENTRYPOINT ["/bin/sh"]
```
```yaml ```yaml
# .gitlab-ci.yml image:
name: super/sql:experimental
image: my-super-sql:experimental entrypoint: [""]
``` ```
After the new extended Docker configuration options, you can now simply **For Docker =< 17.03:**
set an `entrypoint` in `.gitlab-ci.yml`, like:
```yaml ```yaml
# .gitlab-ci.yml
image: image:
name: super/sql:experimental name: super/sql:experimental
entrypoint: ["/bin/sh"] entrypoint: ["/bin/sh", "-c"]
``` ```
As you can see the syntax of `entrypoint` is similar to
[Dockerfile's `ENTRYPOINT`][entrypoint].
## Define image and services in `config.toml` ## Define image and services in `config.toml`
Look for the `[runners.docker]` section: Look for the `[runners.docker]` section:
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment