diff options
| -rw-r--r-- | .gitlab-ci.yml | 115 | ||||
| -rw-r--r-- | Dockerfile | 1 | ||||
| -rw-r--r-- | content/archives/index.md | 35 | ||||
| -rw-r--r-- | dockerfiles/Dockerfile.archives | 17 | ||||
| -rw-r--r-- | dockerfiles/Dockerfile.nginx.onbuild | 10 | ||||
| -rw-r--r-- | dockerfiles/README.md | 61 | ||||
| -rw-r--r-- | layouts/archives.html | 36 |
7 files changed, 239 insertions, 36 deletions
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 1b04071d..4546fa73 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -4,19 +4,26 @@ stages: - images - build - test - - deploy - docker-stable + - deploy -before_script: - - ruby -v - - bundle install --jobs 4 --path vendor - +# +# Pick the remote branch, by default master (see the Rakefile for more info) +# variables: - BRANCH_CE: 'master' # + BRANCH_CE: 'master' BRANCH_EE: 'master' BRANCH_OMNIBUS: 'master' BRANCH_RUNNER: 'master' +before_script: + - ruby -v + - bundle install --jobs 4 --path vendor + +############################################### +# Build the website # +############################################### + .build_base: &build_base stage: build script: @@ -34,23 +41,35 @@ variables: tags: - docker -# Compile on master branch -compile_master: +# +# Compile only on master and stable branches +# +compile_prod: <<: *build_base variables: NANOC_ENV: 'production' only: - master + - /^\d{1,2}\.\d{1,2}$/ +# # Compile on all branches except master -compile_branch: +# +compile_dev: <<: *build_base only: - branches except: - master + - /^\d{1,2}\.\d{1,2}$/ + +############################################### +# Test the website # +############################################### +# # Check for 404s in internal links +# internal_links: stage: test script: @@ -69,7 +88,9 @@ internal_links: except: - pipelines +# # SCSS linting +# scss_lint: stage: test script: @@ -87,13 +108,19 @@ scss_lint: except: - pipelines -# Deploy the Review App +############################################### +# Review Apps # +############################################### + +# +# Deploy the Review App on a dev server +# review: stage: deploy variables: GIT_STRATEGY: none dependencies: - - compile_branch + - compile_dev before_script: [] cache: {} script: @@ -104,13 +131,17 @@ review: on_stop: review_stop only: - branches@gitlab-com/gitlab-docs + # Except master and stable branches except: - master + - /^\d{1,2}\.\d{1,2}$/ tags: - nginx - review-apps +# # Stop the Review App +# review_stop: stage: deploy variables: @@ -127,13 +158,21 @@ review_stop: action: stop only: - branches@gitlab-com/gitlab-docs + # Except master and stable branches except: - master + - /^\d{1,2}\.\d{1,2}$/ tags: - nginx - review-apps -# Deploy to Pages +############################################### +# GitLab Pages (production) # +############################################### + +# +# Deploy to production with GitLab Pages +# pages: stage: deploy variables: @@ -155,11 +194,11 @@ pages: tags: - docker dependencies: - - compile_master + - compile_prod -######################## -# Docker images builds # -######################## +############################################### +# Docker images builds # +############################################### .docker_build: &docker_build image: docker:latest @@ -169,15 +208,20 @@ pages: - docker info - 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 +# image:bootstrap: stage: images <<: *docker_build variables: - DOCKER_DRIVER: overlay2 IMAGE_NAME: $CI_REGISTRY_IMAGE:bootstrap script: - docker build -t $IMAGE_NAME -f dockerfiles/Dockerfile.bootstrap . @@ -185,6 +229,9 @@ image:bootstrap: when: manual <<: *except_stable +# +# Build the image that takes the website and builds it +# image:builder-onbuild: stage: images <<: *docker_build @@ -196,6 +243,9 @@ image:builder-onbuild: when: manual <<: *except_stable +# +# Build the image that copies the final HTML files in a smaller image +# image:nginx-onbuild: stage: images <<: *docker_build @@ -205,26 +255,49 @@ image:nginx-onbuild: - docker build -t $IMAGE_NAME -f dockerfiles/Dockerfile.nginx.onbuild . - docker push $IMAGE_NAME when: manual - <<: *except_stable + only: + - web -# Run only on stable branches +# +# Build the single archive image for stable versions +# image:docs-stable: stage: docker-stable <<: *docker_build variables: + NANOC_ENV: 'production' IMAGE_NAME: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_NAME script: - docker build -t $IMAGE_NAME . - docker push $IMAGE_NAME - # Single or double digits, separated with a dot + # Only branches with versions like 10.4 only: - /^\d{1,2}\.\d{1,2}$/ + except: + - tags -# Run only on master +# +# Build the multiple archives image +# +image:docs-archives: + stage: images + <<: *docker_build + 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 + +# +# Build master containing all archives +# image:docs-latest: stage: docker-stable <<: *docker_build variables: + NANOC_ENV: 'production' IMAGE_NAME: $CI_REGISTRY_IMAGE:latest script: - docker build -t $IMAGE_NAME . @@ -25,7 +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:9.0 ${TARGET} ${TARGET} 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} diff --git a/content/archives/index.md b/content/archives/index.md new file mode 100644 index 00000000..1bfb81ce --- /dev/null +++ b/content/archives/index.md @@ -0,0 +1,35 @@ +--- +layout: archives +--- + +# Docs archives + +CAUTION: **Warning:** +This page is in beta, many links might not work. For updates, follow +[this issue](https://gitlab.com/gitlab-com/gitlab-docs/issues/16). + +Browse the archives for different GitLab versions. + +## 10.5 + +Visit the [GitLab 10.5 docs](/10.5/) or download them and browse locally: + +```sh +docker run -it --rm -p 4000:4000 registry.gitlab.com/gitlab-com/gitlab-docs:10.5 +``` + +## 10.4 + +Visit the [GitLab 10.4 docs](/10.4/) or download them and browse locally: + +```sh +docker run -it --rm -p 4000:4000 registry.gitlab.com/gitlab-com/gitlab-docs:10.4 +``` + +## 10.3 + +Visit the [GitLab 10.3 docs](/10.3/) or 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 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) diff --git a/layouts/archives.html b/layouts/archives.html new file mode 100644 index 00000000..9669dc33 --- /dev/null +++ b/layouts/archives.html @@ -0,0 +1,36 @@ +<!DOCTYPE HTML> +<html lang="en"> + <%= render '/head.*' %> + <body> + <%= render '/header.*' %> + <div class="wrapper"> + <div class="main class js-main-wrapper"> + <% if @config[:breadcrumbs] %> + <% ancestor_array = ancestor_path_array(@item) unless ancestor_path_array(@item).empty? %> + <% if ancestor_array %> + <ul class="breadcrumbs"> + <% ancestor_array.reverse_each do |item| %> + <li class="breadcrumb"><%= link_to item.key?(:title) ? "#{item[:title]}" : "Breadcrumb", item %></li> + <% end %> + <li class="breadcrumb"><%= @item.key?(:title) ? "#{@item[:title]}" : "Current page" %></li> + </ul> + <% end %> + <% end %> + <div id="doc-nav" class="doc-nav"> + </div> + <% if @item[:title] %> + <h1 class="article-title"> + <%= @item[:title] %> + </h1> + <% end %> + <div class="article-content js-article-content"> + <%= yield %> + </div> + </div> + </div> + </body> + + <%= render '/footer.*' %> + <%= render '/analytics.*' %> + <%= render '/https_redirect.*' %> +</html> |