Updating documentation for Docker and Registry

src/site/markdown/docker-config.md

+# Docker Config
+We use the `Docker` runner for [GitLab CI].  This means it is no longer necessary to configure the build server or
+install software required for your build.  Simply declare a [Docker] image in your [.gitlab-ci.yml] file.
+
+## Finding Docker Images
+You can search on [Docker Store] for official images, or [Docker Hub] for community images.
+
+Syntax for official images:
+
+```.gitlab-ci.yml
+image: image:tag
+```
+
+Syntax for community images:
+
+```.gitlab-ci.yml
+image: repo/image:tag
+```
+
+## Missing Required Tooling
+If the image you are using is missing some tooling your build requires, you can either find another image which contains
+the tools you need, or you can build a custom image.  You can either create a completely custom image, or modify an
+existing [Dockerfile] and add the missing tools.  In this case, you may test your image build using your personal
+projects, and then push the project to the [DockerHelper] namespace once the image builds **and** the image can build
+your project without issues.
+
+The `image` tag for custom images is somewhat different from the official and community sources.
+
+```.gitlab-ci.yml
+image: registry.felinewith.me/<namespace>/<project>:<git tag>
+```
+
+Example:
+```.gitlab-ci.yml
+image: registry.felinewith.me/dockerhelper/maven:master
+```
+
+### Custom Image Caveats
+Our server will use the Docker-in-Docker image and tooling for building your custom/modified image.  This means it will
+not work the same way as it would on your machine (if you have Docker installed locally) or on the server (via ssh).
+Additionally, the environment provided by the image you are modifying (with a modified `Dockerfile`) may use different
+package managers.  Fortunately, several images are built using [Alpine Linux], so installing additional software from
+the `apk` repo is fairly easy, as in this example which installs [Git]:
+
+```sh
+apk update
+apk get git
+```
+
+## Example Custom Image
+
+For this example, we will use `registry.felinewith.me/dockerhelper/maven:master`.  The commands for installing `curl`,
+`git`, and `bash` can be seen added at line 10.
+
+The reasons for this were:
+
+* Building the image requires `curl`.
+* Our [maven] builds require `git`.
+* The image requires `bash` for the entrypoint script to work correctly.
+
+**The default `Docker` template for `.gitlab-ci.yml` did not require modification.**
+
+### Pristine
+From https://github.com/carlossg/docker-maven/blob/ecf54b9839caed8aa2bcf9b8f7bb19594634ee89/jdk-8/Dockerfile
+
+```Dockerfile
+FROM openjdk:8-jdk
+
+ARG MAVEN_VERSION=3.5.0
+ARG USER_HOME_DIR="/root"
+ARG SHA=beb91419245395bd69a4a6edad5ca3ec1a8b64e41457672dc687c173a495f034
+ARG BASE_URL=https://apache.osuosl.org/maven/maven-3/${MAVEN_VERSION}/binaries
+
+RUN mkdir -p /usr/share/maven /usr/share/maven/ref \
+  && curl -fsSL -o /tmp/apache-maven.tar.gz ${BASE_URL}/apache-maven-$MAVEN_VERSION-bin.tar.gz \
+  && echo "${SHA}  /tmp/apache-maven.tar.gz" | sha256sum -c - \
+  && tar -xzf /tmp/apache-maven.tar.gz -C /usr/share/maven --strip-components=1 \
+  && rm -f /tmp/apache-maven.tar.gz \
+  && ln -s /usr/share/maven/bin/mvn /usr/bin/mvn
+
+ENV MAVEN_HOME /usr/share/maven
+ENV MAVEN_CONFIG "$USER_HOME_DIR/.m2"
+
+COPY mvn-entrypoint.sh /usr/local/bin/mvn-entrypoint.sh
+COPY settings-docker.xml /usr/share/maven/ref/
+
+VOLUME "$USER_HOME_DIR/.m2"
+
+ENTRYPOINT ["/usr/local/bin/mvn-entrypoint.sh"]
+CMD ["mvn"]
+```
+
+### Modified
+From https://felinewith.me/DockerHelper/maven/blob/9fa955a4ad5ab129165e6529a4fa1312f965d8c6/Dockerfile
+
+```Dockerfile
+# This file is a template, and might need editing before it works on your project.
+FROM openjdk:8-alpine
+
+ARG MAVEN_VERSION=3.5.0
+ARG USER_HOME_DIR="/root"
+ARG SHA=beb91419245395bd69a4a6edad5ca3ec1a8b64e41457672dc687c173a495f034
+ARG BASE_URL=https://apache.osuosl.org/maven/maven-3/${MAVEN_VERSION}/binaries
+
+RUN mkdir -p /usr/share/maven /usr/share/maven/ref \
+  && apk update && apk add curl && apk add git && apk add bash \
+  && curl -fsSl -o /tmp/apache-maven.tar.gz ${BASE_URL}/apache-maven-$MAVEN_VERSION-bin.tar.gz \
+  && echo "${SHA}  /tmp/apache-maven.tar.gz" | sha256sum -c - \
+  && tar -xzf /tmp/apache-maven.tar.gz -C /usr/share/maven --strip-components=1 \
+  && rm -f /tmp/apache-maven.tar.gz \
+  && ln -s /usr/share/maven/bin/mvn /usr/bin/mvn
+
+ENV MAVEN_HOME /usr/share/maven
+ENV MAVEN_CONFIG "$USER_HOME_DIR/.m2"
+
+COPY mvn-entrypoint.sh /usr/local/bin/mvn-entrypoint.sh
+COPY settings-docker.xml /usr/share/maven/ref/
+
+VOLUME "$USER_HOME_DIR/.m2"
+
+ENTRYPOINT ["/usr/local/bin/mvn-entrypoint.sh"]
+CMD ["mvn"]
+```
+
+[GitLab CI]: https://felinewith.me/help/ci/README.md
+[.gitlab-ci.yml]: https://felinewith.me/help/ci/yaml/README.md
+[Docker Store]: https://store.docker.com/
+[Docker Hub]: https://hub.docker.com/
+[Dockerfile]: https://docs.docker.com/engine/reference/builder/
+[DockerHelper]: https://felinewith.me/DockerHelper/
+[Git]: https://git-scm.com/
+[maven]: https://maven.apache.org/

src/site/markdown/gitlab.md

@@ -17,10 +17,10 @@ built on a FreeBSD system.  Worse still, the gRPC team and/or Google does not co
  * https://github.com/grpc/grpc/issues/9721
 
 ## GitLab CI and Docker
-We were unable to configure `gitlab-ci-multi-runner` to use the [Docker] runner.  Installation **always** fails when
-executing `/usr/lib/gitlab-runner/mk-prebuilt-images.sh` at the `cdebootstrap` command.  If this worked, we would be
-using `gitlab-ci-multi-runner` in `Docker` configuration, rather than the current `shell` configuration.  Using the
-`Docker` configuration would mean we would no longer need to configure our server to handle all build tasks.
+We are now using the `Docker` runner in GitLab CI.  Please note, however, not all images contain all the tools required
+for a specific build.  This is because Docker and the Docker Community build generic images.  Most of our [Maven]
+projects require `git` as part of the build and/or versioning process.  To overcome this, it is possible to build
+custom Docker images.  See the [DockerHelper/maven] project as an example.  For more information, see [Docker Config]
 
 [FreeBSD]: https://freebsd.org/
 [Gitaly]: https://gitlab.com/gitlab-org/gitaly
@@ -28,3 +28,7 @@ using `gitlab-ci-multi-runner` in `Docker` configuration, rather than the curren
 [RPC]: https://en.wikipedia.org/wiki/Remote_procedure_call
 [NFS]: https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-nfs.html
 [Docker]: https://docker.io/
+[git]: https://git-scm.com/
+[maven]: https://maven.apache.org/
+[DockerHelper/maven]: https://felinewith.me/DockerHelper/maven
+[Docker Config]: docker-config.html

src/site/markdown/nginx-docker-registry.md

+# nginx configuration for Docker Registry
+Docker Registry only needs a basic HTTP Proxy configuration with [CloudFlare] Origin SSL.
+
+**Note:** Authentication is still handled by Docker Registry.
+
+```nginx
+
+upstream docker-registry {
+  server 172.17.0.3:5000;
+}
+
+map $upstream_http_docker_distribution_api_version $docker_distribution_api_version {
+  '' 'registry/2.0';
+}
+
+## Normal HTTP host
+server {
+  listen 0.0.0.0:80;
+  listen [::]:80;
+  listen 0.0.0.0:443 ssl http2;
+  listen [::]:443 ssl http2;
+  server_name registry.felinewith.me; ## Replace this with something like gitlab.example.com
+  server_tokens off; ## Don't show the nginx version number, a security best practice
+
+  ssl_certificate /***/cf_cert.pem;
+  ssl_certificate_key /***/cf_key.key;
+
+  ## Individual nginx logs for this GitLab vhost
+  access_log  /var/log/nginx/registry_access.log;
+  error_log   /var/log/nginx/registry_error.log;
+
+  client_max_body_size 0;
+  chunked_transfer_encoding on;
+
+  set $ssl off;
+  if ($scheme = https) { set $ssl on; }
+
+  location /v2/ {
+
+    add_header 'Docker-Distribution-Api-Version' $docker_distribution_api_version always;
+
+    proxy_set_header    Host                $http_host;
+    proxy_set_header    X-Real-IP           $http_cf_connecting_ip;
+    proxy_set_header    X-Forwarded-For     $http_x_forwarded_for;
+    proxy_set_header    X-Forwarded-Proto   $scheme;
+    proxy_set_header    X-Forwarded-Ssl     $ssl;
+    proxy_set_header    Upgrade             $http_upgrade;
+    proxy_set_header    Connection          $connection_upgrade_gitlab;
+    proxy_set_header    REMOTE_ADDR         $http_cf_connecting_ip;
+
+    proxy_read_timeout 900;
+
+    proxy_pass http://docker-registry;
+  }
+
+}
+```
+
+[CloudFlare]: https://cloudflare.com/
+

src/site/site.xml

@@ -39,10 +39,12 @@
 		<menu name="Configuration" ref="config">
 			<item name="Your Tools" href="your-tools.html" />
 			<item name="GitLab" href="gitlab.html" />
+			<item name="Docker Config" href="docker-config.html" />
 			<item name="nginx" href="nginx.html">
 				<item name="nginx GitLab" href="nginx-gitlab.html" />
 				<item name="nginx GitLab Pages" href="nginx-gitlab-pages.html" />
 				<item name="nginx Archiva" href="nginx-archiva.html" />
+				<item name="nginx Docker Registry" href="nginx-docker-registry.html" />
 			</item>
 		</menu>
 		<menu name="Project Information" ref="reports" inherit="bottom" />