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

Fix entrypoint overriding documentation

See merge request gitlab-org/gitlab-ce!15884

(cherry picked from commit a2c615d16948301f91d704acd7386d2c0efb5ccd)

b17c3ab6 Fix entrypoint overriding documentation
9f3df649 Refactor entrypoint override docs

1 files changed, 39 insertions, 22 deletions

diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md
index ecb8f15c851..fb5bfe26bb0 100644
--- a/doc/ci/docker/using_docker_images.md
+++ b/doc/ci/docker/using_docker_images.md
@@ -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
 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
 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
 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
-entrypoint or at least will start with a shell as its entrypoint.
-
-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:
+entrypoint or that the entrypoint is prepared to start a shell command.
 
-```Dockerfile
-# my-super-sql:experimental image's Dockerfile
+With the extended Docker configuration options, instead of creating your
+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
-ENTRYPOINT ["/bin/sh"]
-```
+**For Docker 17.06+:**
 
 ```yaml
-# .gitlab-ci.yml
-
-image: my-super-sql:experimental
+image:
+  name: super/sql:experimental
+  entrypoint: [""]
 ```
 
-After the new extended Docker configuration options, you can now simply
-set an `entrypoint` in `.gitlab-ci.yml`, like:
+**For Docker =< 17.03:**
 
 ```yaml
-# .gitlab-ci.yml
-
 image:
   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`
 
 Look for the `[runners.docker]` section: