Merge branch 'enable-versions-backend' into 'master'

Enable versions in backend

See merge request gitlab-com/gitlab-docs!232

6 files changed, 100 insertions, 62 deletions

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 8a00e23e..dcb6fe68 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -1,12 +1,11 @@
 image: ruby:2.5
 
 stages:
-  - images
+  - build-images
   - build
   - test
   - deploy
-  - performance
-  - docker-stable
+  - post-deploy
 
 #
 # Pick the remote branch, by default master (see the Rakefile for more info)
@@ -28,6 +27,12 @@ before_script:
 .except_pipelines: &except_pipelines
   except:
     - pipelines
+#
+# Except stable branches (with names like '10.4', '11.2', etc.)
+#
+.except_stable: &except_stable
+  except:
+    - /^\d{1,2}\.\d{1,2}$/
 
 ###############################################
 #             Build the website               #
@@ -177,6 +182,7 @@ review_stop:
 # Deploy to production with GitLab Pages
 #
 pages:
+  image: registry.gitlab.com/gitlab-com/gitlab-docs:latest
   stage: deploy
   variables:
     GIT_STRATEGY: none
@@ -185,6 +191,8 @@ pages:
   environment:
     name: production
     url: https://docs.gitlab.com
+  dependencies:
+    - compile_prod    # Contains the public directory
   script:
     - echo $CI_ENVIRONMENT_URL > environment_url.txt
     # Symlink all README.html to index.html
@@ -198,15 +206,13 @@ pages:
     - master@gitlab-com/gitlab-docs
   tags:
     - docker
-  dependencies:
-    - compile_prod
 
 ###############################################
 #           Performance testing               #
 ###############################################
 
 performance:
-  stage: performance
+  stage: post-deploy
   image: docker:git
   services:
     - docker:dind
@@ -231,7 +237,10 @@ performance:
 #           Docker images builds              #
 ###############################################
 
-.docker_build: &docker_build
+#
+# Reuse some common commands
+#
+.docker_prepare: &docker_prepare
   image: docker:latest
   services:
     - docker:dind
@@ -240,18 +249,12 @@ performance:
     - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
 
 #
-# Except stable branches with versions like 10.4
-#
-.except_stable: &except_stable
-  except:
-    - /^\d{1,2}\.\d{1,2}$/
-
-#
-# Build the image containing all build dependencies
+# Helper Docker image containing all build dependencies
+# It must be rebuilt every time Gemfile.lock changes
 #
 image:bootstrap:
-  stage: images
-  <<: *docker_build
+  stage: build-images
+  <<: *docker_prepare
   variables:
     IMAGE_NAME: $CI_REGISTRY_IMAGE:bootstrap
   script:
@@ -261,11 +264,11 @@ image:bootstrap:
   <<: *except_stable
 
 #
-# Build the image that takes the website and builds it
+# Helper Docker image that builds the gitlab-docs website
 #
 image:builder-onbuild:
-  stage: images
-  <<: *docker_build
+  stage: build-images
+  <<: *docker_prepare
   variables:
     IMAGE_NAME: $CI_REGISTRY_IMAGE:builder-onbuild
   script:
@@ -275,31 +278,33 @@ image:builder-onbuild:
   <<: *except_stable
 
 #
-# Build the image that copies the final HTML files in a smaller image
+# Helper Docker image that copies the final HTML files in a smaller image
+# (no rubygems included)
 #
 image:nginx-onbuild:
-  stage: images
-  <<: *docker_build
+  stage: build-images
+  <<: *docker_prepare
   variables:
     IMAGE_NAME: $CI_REGISTRY_IMAGE:nginx-onbuild
   script:
     - docker build -t $IMAGE_NAME -f dockerfiles/Dockerfile.nginx.onbuild .
     - docker push $IMAGE_NAME
   when: manual
-  only:
-    - web
+  <<: *except_stable
 
 #
-# Build the single archive image for stable versions
+# Final Docker image containing a single version
+# It is based on Dockerfile.single for each branch
 #
-image:docs-stable:
-  stage: docker-stable
-  <<: *docker_build
+image:docs-single:
+  stage: post-deploy
+  <<: *docker_prepare
   variables:
     NANOC_ENV: 'production'
     IMAGE_NAME: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_NAME
+    DOCKERFILE: Dockerfile.$CI_COMMIT_REF_NAME
   script:
-    - docker build --build-arg NANOC_ENV=${NANOC_ENV} --build-arg CI_COMMIT_REF_NAME=${CI_COMMIT_REF_NAME} -t $IMAGE_NAME .
+    - docker build --build-arg NANOC_ENV=${NANOC_ENV} --build-arg CI_COMMIT_REF_NAME=${CI_COMMIT_REF_NAME} -t $IMAGE_NAME -f $DOCKERFILE .
     - docker push $IMAGE_NAME
   # Only branches with versions like 10.4
   only:
@@ -308,31 +313,34 @@ image:docs-stable:
     - tags
 
 #
-# Build the multiple archives image
+# Final Docker image containing all the archives
 #
 image:docs-archives:
-  stage: images
-  <<: *docker_build
+  stage: post-deploy
+  <<: *docker_prepare
   variables:
     IMAGE_NAME: $CI_REGISTRY_IMAGE:archives
   script:
     - docker build -t $IMAGE_NAME -f dockerfiles/Dockerfile.archives .
     - docker push $IMAGE_NAME
-  when: manual
-  <<: *except_stable
+  # Run only on schedules since this will contain only the archives
+  only:
+    - schedules
 
 #
-# Build master containing all archives and latest docs
+# Build master containing the online archives and latest docs (on schedules)
 #
 image:docs-latest:
-  stage: docker-stable
-  <<: *docker_build
+  stage: post-deploy
+  <<: *docker_prepare
   variables:
     NANOC_ENV: 'production'
     IMAGE_NAME: $CI_REGISTRY_IMAGE:latest
+    DOCKERFILE: Dockerfile.$CI_COMMIT_REF_NAME
   script:
-    - docker build --build-arg NANOC_ENV=${NANOC_ENV} --build-arg CI_COMMIT_REF_NAME=${CI_COMMIT_REF_NAME} -t $IMAGE_NAME .
+    - docker pull $IMAGE_NAME || true
+    - docker build --cache-from $IMAGE_NAME --build-arg NANOC_ENV=${NANOC_ENV} --build-arg CI_COMMIT_REF_NAME=${CI_COMMIT_REF_NAME} -t $IMAGE_NAME -f $DOCKERFILE .
     - docker push $IMAGE_NAME
-  only:
-    - master
   allow_failure: true
+  only:
+    - schedules
diff --git a/Dockerfile b/Dockerfile.master
index bacf6f64..548b9734 100644
--- a/Dockerfile
+++ b/Dockerfile.master
@@ -25,9 +25,6 @@ RUN rm -rf /usr/share/nginx/html/*
 # 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}
 COPY --from=registry.gitlab.com/gitlab-com/gitlab-docs:10.6 ${TARGET} ${TARGET}
 
 # Get the built docs output from the previous build stage
diff --git a/content/archives/index.md b/content/archives/index.md
index 9aabd9f3..d8a66075 100644
--- a/content/archives/index.md
+++ b/content/archives/index.md
@@ -10,7 +10,12 @@ This page is in beta, many links might not work. For updates, follow
 
 Browse the archives for different GitLab versions.
 
-## 10.6
+## Online archives
+
+The following archives are available online and can be browsed on
+<https://docs.gitlab.com>.
+
+### 10.6
 
 Visit the [GitLab 10.6 docs](/10.6/) or download them and browse locally:
 
@@ -18,25 +23,29 @@ Visit the [GitLab 10.6 docs](/10.6/) or download them and browse locally:
 docker run -it --rm -p 4000:4000 registry.gitlab.com/gitlab-com/gitlab-docs:10.6
 ```
 
-## 10.5
+## Offline archives
+
+The following archives are available offline.
+
+### 10.5
 
-Visit the [GitLab 10.5 docs](/10.5/) or download them and browse locally:
+Download them and browse locally:
 
 ```sh
 docker run -it --rm -p 4000:4000 registry.gitlab.com/gitlab-com/gitlab-docs:10.5
 ```
 
-## 10.4
+### 10.4
 
-Visit the [GitLab 10.4 docs](/10.4/) or download them and browse locally:
+Download them and browse locally:
 
 ```sh
 docker run -it --rm -p 4000:4000 registry.gitlab.com/gitlab-com/gitlab-docs:10.4
 ```
 
-## 10.3
+### 10.3
 
-Visit the [GitLab 10.3 docs](/10.3/) or download them and browse locally:
+Download them and browse locally:
 
 ```sh
 docker run -it --rm -p 4000:4000 registry.gitlab.com/gitlab-com/gitlab-docs:10.3
diff --git a/dockerfiles/Dockerfile.archives b/dockerfiles/Dockerfile.archives
index e824bca6..31ab003b 100644
--- a/dockerfiles/Dockerfile.archives
+++ b/dockerfiles/Dockerfile.archives
@@ -12,6 +12,7 @@ COPY --from=registry.gitlab.com/gitlab-com/gitlab-docs:nginx-onbuild /etc/nginx/
 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}
+COPY --from=registry.gitlab.com/gitlab-com/gitlab-docs:10.6 ${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/Dockerfile.archive b/dockerfiles/Dockerfile.single
index 843ebd54..d3aa144a 100644
--- a/Dockerfile.archive
+++ b/dockerfiles/Dockerfile.single
@@ -1,5 +1,5 @@
 #
-# Copy this Dockerfile to each branch you want to create an archive
+# Copy this Dockerfile to the root of each branch you want to create an archive
 #
 
 # Set to the version for this archive (must match the branch name)
@@ -13,8 +13,10 @@ ARG BRANCH_RUNNER=10-4-stable
 
 # This image comes from the Dockerfile.builder.onbuild file
 # https://gitlab.com/gitlab-com/gitlab-docs/blob/master/dockerfiles/Dockerfile.builder.onbuild
+# Build the website
 FROM registry.gitlab.com/gitlab-com/gitlab-docs:builder-onbuild AS builder
 
 # This image comes from the Dockerfile.nginx.onbuild file
 # https://gitlab.com/gitlab-com/gitlab-docs/blob/master/dockerfiles/Dockerfile.nginx.onbuild
+# Copy the generated HTML files to a smaller image
 FROM registry.gitlab.com/gitlab-com/gitlab-docs:nginx-onbuild
diff --git a/dockerfiles/README.md b/dockerfiles/README.md
index 1c0dbfab..e09ed89b 100644
--- a/dockerfiles/README.md
+++ b/dockerfiles/README.md
@@ -15,7 +15,7 @@ The following Dockerfiles are used.
 
 ## How to build the images
 
-Build and tag all tooling images:
+You can build and tag all tooling images locally (while in this directory):
 
 ```sh
 docker build -t registry.gitlab.com/gitlab-com/gitlab-docs:bootstrap -f Dockerfile.bootstrap ../
@@ -26,11 +26,17 @@ docker build -t registry.gitlab.com/gitlab-com/gitlab-docs:nginx-onbuild -f Dock
 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.
 
-## Create an archive image for a single version
+## When a new version is released
+
+When a new version is released, we need to create the single Docker image,
+and update the `latest` and `archives` images to include the new version.
+
+### Create an image for a single version
 
 Now that all required images are created, you can build the archive for each
 branch:
 
+1. Make sure you're on the root path of the repo
 1. Create the branch if it doesn't exist. Name the branch by using the major
    minor versions:
 
@@ -38,10 +44,10 @@ branch:
     git checkout -b 10.5
     ```
 
-1. Copy the Dockerfile.archive to Dockerfile:
+1. Copy `Dockerfile.single` to `Dockerfile.$version` in the root path:
 
     ```
-    cp Dockerfile{.archive,}
+    cp dockerfiles/Dockerfile.single Dockerfile.10.5
     ```
 
 1. Edit the Dockerfile and add the correct version:
@@ -63,24 +69,39 @@ branch:
 1. Test locally by building the image and running it:
 
     ```
-    docker build -t docs:10.5 .
+    docker build -t docs:10.5 -f Dockerfile.10.5 .
     docker run -it --rm -p 4000:4000 docs:10.5
     ```
 
-1. Visit http://localhost:4000/10.5/ and make sure everything works correctly
+1. Visit <http://localhost:4000/10.5/> and make sure everything works correctly
 1. Commit your changes and push (don't create a merge request)
 
-Once you push, the `image:docker-stable` job will create a new Docker image
+Once you push, the `image:docker-singe` job will create a new Docker image
 tagged with the branch name.
 
-## Update the multiple archives image
+Rerun the pipeline for the branch if there are upstream changes not included
+in the image.
+
+## Updating the `latest` and `archives` images
+
+**Note:** Make sure the single image is built first.
 
-With every new release on the 22nd, the archives Docker image should be updated.
-Edit the following files and add the new version:
+With every new release on the 22nd, we need to update the `latest` and `archives`
+Docker images.
+
+For the `archives`, edit the following files and add the new version:
 
 - `content/archives/index.md`
 - [`Dockerfile.archives`](Dockerfile.archives)
 
+For the `latest`, edit the following file and add the new version:
+
+- [`Dockerfile.master`](../Dockerfile.master)
+
+Once you push, the new `latest` image will be built and it will contain the new
+version. You may need to run the pipeline on master one more for the website
+to have all the versions. The `archives` runs on a schedule, usually once an hour.
+
 ## Porting new website changes to old versions
 
 The website will keep changing and being improved. In order to consolidate