Deploying the docs

There are two ways to build the deploy the docs; either doing a full build from source or a build using the 11ty and web base images. A build from source should be used when the starter kit has been used as the base of a new site and changes have been made to 11ty and any assets. It requires all the 11ty starter kit files to be in the repo. A build using base images can be used when converting a docs folder into a site without making any changes to the starter kit.

Both builds can be done through GitLab CI or manually. GitLab CI is the easiest and preferred way to deploy the docs. The manual steps are useful when developing or debugging the deployment process.

Automatic build and deploy

The preferred way to build and deploy the site is to do this automatically using GitLab CI. This can be done by including the desired build and deploy YAML file and, optionally, configuring the URL to deploy thr site to.

There are 3 build files that can be used depending on the desired functionality.

Automatic build from source

This builds the site from the 11ty sources files in the repo into a Docker container. The default branch is deployed to the URL defined in the SITE_URL variable; which be default is {SITE_ID}.docs.agile.coop. Long running environments are created when branches are created without a slash (/) in the name. For example, to create a stage environment, create and push a stage branch, which will create a new site based off this branch at stage.{ SITE_ID }.docs.agile.coop. New testing environments are automatically created when a merge request is created and destroyed when the merge request is closed.

To use this, include the build-deploy-docs-source.yml file in the repos .gitlab-ci.yml files and optionally set the SITE_ID. If the SITE_ID is not set the GitLab project name is used.

include:
  - https://gitlab.agile.coop/docs/11ty-docs-starter-kit/-/raw/1.x/.gitlab-ci/build-deploy-docs-source.yml

variables:
  SITE_ID: my-site-id

Automatic build using base images

The build with base images creates the same environments as the automatic build from source except is doesn't require all the 11ty files in the git repo as these are built into the base images.

To use this, include the build-deploy-docs-images.yml file in the repos .gitlab-ci.yml file and set the SITE_ID. If the SITE_ID is not set the GitLab project name is used.

include:
  - https://gitlab.agile.coop/docs/11ty-docs-starter-kit/-/raw/1.x/.gitlab-ci/build-deploy-docs-images.yml

Build standalone docs directory

Use the standalone docs build and deploy when creating a site for a docs directory in an existing repo. By default, this will create a site with the URL {GitLab project}.{GitLab namespace}.docs.agile.coop. Unlike the other automatic builds, the site is only built when there are changes to the docs directory in the repos main branch.

To use this, simply include the build-deploy-docs-standalone.yml in the repos .gitlab-ci.yml file.

include:
  - https://gitlab.agile.coop/docs/11ty-docs-starter-kit/-/raw/1.x/.gitlab-ci/build-deploy-docs-standalone.yml

Deployment variables

It is possible to customise the GitLab build and deploy by setting variables in the .gitlab-ci.yml file. The most useful variables are discussed below. For a complete list see the base-build-deploy-docs.yml file.

SITE_ID

This configures a name slug for the site which is used to set the URL with the form https://{SITE_ID}.{BASE_URL}. It defaults to the GitLab project name, so there's no need to set this if the SITE_ID is the same as the git repo name.

BASE_URL

This is use to create the URL for the site along with the SITE_ID. For this to work there needs to be wildcard DNS records pointing BASE_URL to the IP addresses of Kubernetes load balancer / ingress. It defaults to docs.agile.coop.

SITE_URL

This sets the URL of the production site. By default it's SITE_ID.BASE_URL. It's not recommended to change this, but if it is, like BASE_URL, it must resolve to the IP addresses of the Kubernetes cluster.

GitLab configuration

For automatic deployments to work GitLab needs to be able to authenticate with the Kubernetes cluster. This is done by setting some variables in GitLab that are passed to the CI pipeline. For security reasons these are not set globally and need to be added to any projects that want to create a docs site.

You do not need to add any GitLab configuration if your site lives in the docs group as this is already set for you.

To set these, in the project in GitLab, select Settings >> CI/CD. Expand Variables and add the following:

Key: K8S_USER_TOKEN
Value: found in Passbolt under GitLab K8s user token
Type: Variable
Check the 'Mask variable' flag

Key: K8S_CERTIFICATE_AUTHORITY_DATA
Value: found in Passbolt under GitLab K8s certificate
Type: Variable
Check the 'Mask variable' flag

It's also necessary to ensure that shared runners are enabled for the project. On the same page, expand Runners and ensure 'Enable shared runners for this project' is on.

Manual Docker builds

Authenticating with GitLab

To be able to push Docker images to GitLab it is necessary to authenticate with the container registry. As gitlab.agile.coop has 2FA enabled this will need to be done using an access token. The access token should have the read_registry and write_registry scopes.

Login with:

docker login -u $GITLAB_USER -p $GITLAB_ACCESS_TOKEN gitlab.agile.coop:5050

Where:

Manual build from source

This uses the Docker multistep build file in .gitlab-ci/build-source to install 11ty, compile the docs and then build these into a Docker image that is pushed into the GitLab container registry.

export DOCKER_IMAGE=gitlab.agile.coop:5050/docs/11ty-docs-starter-kit:latest
export ELEVENTY_ENV=development
docker build -f .gitlab-ci/build-source/Dockerfile -t $DOCKER_IMAGE --build-arg ELEVENTY_ENV=$ELEVENTY_ENV .
docker push $DOCKER_IMAGE

The built image be tested by running docker run -p 8080:80 -t $DOCKER_IMAGE and going to http://localhost:8080.

Manual build using base images

Partial builds are used when you want to publish a docs directory and don't want to make changes to the starter kits styling. This uses the starter kit base image to build the docs without having to install 11ty and the starter kit assets.

The Docker file for this can can found in .gitlab-ci/build-images and can be built with the following.

export DOCKER_IMAGE=gitlab.agile.coop:5050/docs/11ty-docs-starter-kit:latest
export ELEVENTY_ENV=development
docker build -f .gitlab-ci/build-images/Dockerfile -t $DOCKER_IMAGE --build-arg ELEVENTY_ENV=$ELEVENTY_ENV .
docker push $DOCKER_IMAGE

The variables and testing instructions it are the same as the full build above.

Manually building 11ty base image

The partial build uses the starter kit base image to compile the docs directory using 11ty. This is updated automatically whenever changes are merged in to the default branch using GitLab CI, but can be built with the following.

export DOCKER_IMAGE=gitlab.agile.coop:5050/docs/11ty-docs-starter-kit:base
docker build -f .gitlab-ci/build-base/Dockerfile -t $DOCKER_IMAGE .
docker push $DOCKER_IMAGE

Manually building Nginx web image

Partial builds use the starter kit web image to build the site into a container that can be hosted in Kubernetes. Tob build this manually use the following.

export DOCKER_IMAGE=gitlab.agile.coop:5050/docs/11ty-docs-starter-kit:web
docker build -f .gitlab-ci/build-web/Dockerfile -t $DOCKER_IMAGE .
docker push $DOCKER_IMAGE

Manual Kubernetes deploy

To perform a manual deploy a Kubernetes (K8s) cluster you'll need to have kubectl installed and configured with permissions to create deployments. For Agile Collective members see the accessing Kubernetes documentation.

The K8s deploy uses the manifests file found in .gitlab-ci/deploy-k8s/manifests.yml file. This creates a deployment, service and ingress.

export DOCKER_IMAGE=gitlab.agile.coop:5050/docs/11ty-docs-starter-kit:latest
export ELEVENTY_ENV=production
export SITE_ID=starter-kit
export SITE_URL=starterkit.docs.agile.coop
envsubst < .gitlab-ci/deploy-k8s/manifest.yml | kubectl apply -f -

A short while after the command completes, and assuming everything ran successfully, the site will be available on the provided URL.

Build modes

There are 3 build modes that are passed to the 11ty build process as the ELEVENTY_ENV environmental variable.

For GitLab CI deployments, production deploys are built for production, all other deployments are build for stage.

These variables are set automatically when builds are run using npm scripts.

Last updated: