How to deploy a Docusaurus website to K8s

Alberto — Wed, 04 Aug 2021 13:18:03 +0000

First, let me give you a bit of background.

At my company we're looking for a way to create and share internal documentation with a git and Markdown-based documentation service.

The reasons behind these choices are that (1) Markdown is simple to use and all the developers know how to use it; and (2) a git-based service will help us track documentation changes and agree on improvements by using pull requests and "doc reviews" before merging any changes.

After some searching around we decided to go with Docusaurus a static documentation site generator created by Facebook.

We really enjoy it since it is based in React Native and once things are set up it is very easy to submit a new doc page or make changes.

But when we first started using it we found ourselves with a deployment issue. We wanted to keep the documentation private and didn't want to use any of the services that the docusuarus team propose (Netlify, GitHub Pages, etc.). Instead, we decided to host it on our own "dev" Kubernetes cluster so that we could access it via our proxy and VPN.

I didn't find any information on how to do this online, so here are the steps I followed in case you find yourself with the same issue:

Deployment Steps

I'll assume that you already have a docusuarus website that you can run locally using yarn, yarn build, yarn serve (or their npm equivalents).
With that out of the way you'll just need to build a docker image:

FROM node:12.19.0-alpine

WORKDIR /app

COPY . /app

RUN yarn

RUN yarn build

ENTRYPOINT ["yarn", "run", "serve"]

Push the new image to your preferred docker registry
And finally apply a k8s deployment to your cluster. Save and adjust the below yaml and then simply run kubectl apply -f deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ms-docs
spec:
  selector:
    matchLabels:
      app: ms-docs
  template:
    metadata:
      labels:
        app: ms-docs
    spec:
      containers:
      - name: ms-docs
        envFrom:
        - configMapRef:
            name: ms-docs
        image: my-registry/ms-docs:stable
        imagePullPolicy: Always
        livenessProbe:
          failureThreshold: 15
          httpGet:
            path: /
            port: 3000
          initialDelaySeconds: 20
          periodSeconds: 15
          timeoutSeconds: 5
        ports:
        - containerPort: 80
          name: http
          protocol: TCP
        readinessProbe:
          failureThreshold: 15
          httpGet:
            path: /
            port: 3000
          initialDelaySeconds: 20
          periodSeconds: 15
          timeoutSeconds: 5
        resources:
          limits:
            cpu: "500m"
            memory: 384Mi
          requests:
            cpu: "500m"
            memory: 384Mi
--------
apiVersion: v1
kind: Service
metadata:
  name: ms-docs
spec:
  ports:
  - name: http
    port: 3000
    protocol: TCP
    targetPort: 3000
  selector:
    app: ms-docs
  type: ClusterIP

Automated Semantic Versions for all projects with semantic-release and Gitlab CI!

Alberto — Thu, 10 Oct 2019 16:25:57 +0000

Introduction

When software projects start to mature, there usually comes a time when you need to start versioning your releases and publishing Changelogs.

Most programmers have ways to tackle this issue either by doing things manually and maybe keeping track of a version file in the project or by using ad-hoc scripts that never quite work.

At least this has been the case for me. This is why I started searching for solutions that would be agnostic to the type of project and language used and that could be easily added to my CI pipelines.

After some browsing and experimenting I've found a robust solution with
semantic-release and Gitlab CI that can be used with any project.

The rest of this post describes this solution.

Semantic Release

Semantic-release is an npm tool that automates the process of
generating a new semantic version and Changelog for your project. All you have to do is adapt your commit messages to follow the angular commits convention.

The tool works by scanning your commits history from the most recent tag
and increments the version number based on the commits:

a fix commit increments the patch number of the version (the rightmost
number).
a feat commit increments the minor number of the version (the middle
number).
a BREAKING CHANGE commits increments the major number of the version (the
leftmost number).

For example, suppose that your latest semantic version is 2.1.0 and you had to push a bugfix twith the commit message fix: div by zero. Your next release would be tagged 2.1.1.

Since the tool is simply looking at your commits history, this means that we can use it with any project that uses Git. There are no restrictions on languages or frameworks. Moreover, there are plugins both for GitHub and Gitlab that simplify the process of committing and pushing new tags to the repository of the project as we will see next.

Gitlab CI

I'm a big fan of Gitlab's integrated CI pipelines. All you need to do to
automate your workflow is to create a new project on Gitlab and add a
.gitlab-ci.yml file to the root of your project. Gitlab's own runners will then do its magic.

Thanks to the Gitlab plugin for semantic-release, creating a CI job for
releasing new tags is as simple as:

stages:
 - tag

semantic_release:
  stage: tag
  image: node:8
  variables:
      GITLAB_TOKEN: $ACCESS_TOKEN
  before_script:
      - npm install -g semantic-release @semantic-release/gitlab-config
      - cat $SEM_RELEASE_OPTIONS > .releaserc.yml
  script:
      - semantic-release -e @semantic-release/gitlab-config
  only:
      - master

After this there are only two things left to do:

You will need to create a personal access token and add it to the CI/CD Variables of your project. For this go to Settings > CI/CD > Variables and create a new variable named ACCESS_TOKEN. In the value field put your access token.
Semantic-release has configurable options that the tool can use. These can be set in a package.json file or a releaserc.yml file at the root of the project.

I've opted for the second option with a tweak. Rather than keeping the file in my project under version control, I created another CI/CD variable and pasted the options there.

To do this copy the below file into a SEM_RELEASE_OPTIONS variable of type File in your CI/CD variables on Gitlab.

branch: master
publish: ['@semantic-release/gitlab']
verifyConditions: ['@semantic-release/gitlab']

With this, Gitlab will use semantic-release to publish a new version every time a new commit lands on the master branch of your project and you can sit back and relax!