Add an archive Docker image and a test archives page

3 files changed, 74 insertions, 14 deletions

diff --git a/dockerfiles/Dockerfile.archives b/dockerfiles/Dockerfile.archives
new file mode 100644
index 00000000..e824bca6
--- /dev/null
+++ b/dockerfiles/Dockerfile.archives
@@ -0,0 +1,17 @@
+FROM nginx:alpine
+
+ENV TARGET=/usr/share/nginx/html
+
+# Get the nginx config from the nginx-onbuild image
+# This hardly ever changes so should usually be cached
+COPY --from=registry.gitlab.com/gitlab-com/gitlab-docs:nginx-onbuild /etc/nginx/conf.d/default.conf /etc/nginx/conf.d/default.conf
+
+# Get all the archive static HTML and put it into place
+# Go oldest-to-newest to take advantage of the fact that we change older
+# archives less often than new ones.
+COPY --from=registry.gitlab.com/gitlab-com/gitlab-docs:10.3 ${TARGET} ${TARGET}
+COPY --from=registry.gitlab.com/gitlab-com/gitlab-docs:10.4 ${TARGET} ${TARGET}
+COPY --from=registry.gitlab.com/gitlab-com/gitlab-docs:10.5 ${TARGET} ${TARGET}
+
+# Serve the site (target), which is now all static HTML
+CMD echo -e "GitLab docs are viewable at:\nhttp://0.0.0.0:4000"; exec nginx -g 'daemon off;'
diff --git a/dockerfiles/Dockerfile.nginx.onbuild b/dockerfiles/Dockerfile.nginx.onbuild
index 34ebb7c8..74a041ee 100644
--- a/dockerfiles/Dockerfile.nginx.onbuild
+++ b/dockerfiles/Dockerfile.nginx.onbuild
@@ -1,14 +1,16 @@
-# Base image to use for building documentation archives
-# this image uses "ONBUILD" to perform all required steps in the archives
+# Base image to use for building documentation archives.
+# This image uses "ONBUILD" to perform all required steps in the archives
 # and relies upon its parent image having a layer called `builder`.
 
 FROM nginx:alpine
 
-# Make the version accessible to this build-stage, and copy it to an ENV so that it persists in the final image
+# Make the version accessible to this build-stage, and copy it to an ENV so
+# that it persists in the final image.
 ONBUILD ARG VER
 ONBUILD ENV VER=$VER
 
-# Clean out any existing HTML files, and copy the HTML from the builder stage to the default location for Nginx
+# Clean out any existing HTML files, and copy the HTML from the builder stage
+# to the default location for Nginx.
 ONBUILD RUN rm -rf /usr/share/nginx/html/*
 ONBUILD COPY --from=builder /site /usr/share/nginx/html
 
diff --git a/dockerfiles/README.md b/dockerfiles/README.md
index 3e8b2b4e..efc5fde2 100644
--- a/dockerfiles/README.md
+++ b/dockerfiles/README.md
@@ -3,17 +3,17 @@
 This directory contains all needed Dockerfiles to build and deploy the website.
 It is heavily inspired by Docker's [publish tools](https://github.com/docker/docker.github.io/tree/publish-tools).
 
-## When to update the Dockerfiles
+The following Dockerfiles are used.
 
 | Dockerfile | Docker image | Description |
 | ---------- | ------------ | ----------- |
-| `Dockerfile.bootstrap` | `gitlab-docs:bootstrap` | This image contains all the dependencies that are needed to build the website. If the gems are updated and `Gemfile{,.lock}`  changes, the image must be rebuilt. |
+| [`Dockerfile.bootstrap`](Dockerfile.bootstrap) | `gitlab-docs:bootstrap` | Contains all the dependencies that are needed to build the website. If the gems are updated and `Gemfile{,.lock}` changes, the image must be rebuilt. |
+| [`Dockerfile.builder.onbuild`](Dockerfile.builder.onbuild) | `gitlab-docs:builder-onbuild` | Base image to build the docs website. It uses `ONBUILD` to perform all steps and depends on `gitlab-docs:bootstrap`. |
+| [`Dockerfile.nginx.onbuild`](Dockerfile.nginx.onbuild) | `gitlab-docs:nginx-onbuild` | Base image to use for building documentation archives. It uses `ONBUILD` to perform all required steps to copy the archive, and relies upon its parent `Dockerfile.builder.onbuild` that is invoked when building single documentation achives (see the `Dockerfile` of each branch. |
+| [`Dockerfile.archives`](Dockerfile.archives) | `gitlab-docs:archives` | Contains all the versions of the website in one archive. It copies all generated HTML files from every version in one location. |
 
 ## How to build the images
 
-For each image, there's a manual job under the `images` stage in
-[`.gitlab-ci.yml`](../.gitlab-ci.yml).
-
 Build and tag all tooling images:
 
 ```sh
@@ -22,9 +22,50 @@ docker build -t registry.gitlab.com/gitlab-com/gitlab-docs:builder-onbuild -f Do
 docker build -t registry.gitlab.com/gitlab-com/gitlab-docs:nginx-onbuild -f Dockerfile.nginx.onbuild ../
 ```
 
-For each archive branch, build the archive's image:
+For each image, there's a manual job under the `images` stage in
+[`.gitlab-ci.yml`](../.gitlab-ci.yml) which can be invoked at will.
 
-```
-git checkout 10-4-stable
-docker build -t registry.gitlab.com/gitlab-com/gitlab-docs/docs:10.4 .
-```
+## Create an archive image for a single version
+
+Now that all required images are created, you can build the archive for each
+branch:
+
+1. Create the branch if it doesn't exist. Name the branch by using the major
+   minor versions:
+
+    ```
+    git checkout -b 10.5
+    ```
+
+1. Copy the Dockerfile.archive to Dockerfile:
+
+    ```
+    cp Dockerfile{.archive,}
+    ```
+
+1. Edit the Dockerfile and add the correct version:
+
+    ```
+    # The branch of the docs repo from step 1
+    ARG VER=10.5
+
+    # Replace the versions to match the stable branches of the upstream projects
+    ARG BRANCH_EE=10-5-stable-ee
+    ARG BRANCH_CE=10-5-stable
+    ARG BRANCH_OMNIBUS=10-5-stable
+    ARG BRANCH_RUNNER=10-5-stable
+
+    FROM registry.gitlab.com/gitlab-com/gitlab-docs:builder-onbuild AS builder
+    FROM registry.gitlab.com/gitlab-com/gitlab-docs:nginx-onbuild
+    ```
+
+Once you push, the `image:docker-stable` job will create a new Docker image
+tagged with the branch name.
+
+## Update the multiple archives image
+
+With every new release on the 22nd, the archives Docker image should be updated.
+Edit the following files and add the new version:
+
+- `content/archives/index.md`
+- [`Dockerfile.archives`](/Dockerfile.archives)