FAQ | This is a LIVE service | Changelog

Skip to content
Snippets Groups Projects

DevOps Guidebook

This repository contains the source for the UIS DevOps Guidebook

Developing locally

The guidebook uses mkdocs to convert Markdown source into a static website. You can run it from either the dockerised setup or your own local environment.

To begin development, install pre-commit and clone the repo locally:

git clone git@gitlab.developers.cam.ac.uk:uis/devops/docs/guidebook.git
pre-commit install

Using Docker

docker-compose up

The local documentation is now available at http://localhost:8000/.

Using your local environment

Install mkdocs using pip:

pip3 install --user -r requirements.txt

You can then serve a site locally for development via mkdocs:

mkdocs serve

The local documentation is now available at http://localhost:8000/.

Adding a page

  1. Create a Markdown file in the relevant directory under docs.
  2. Add this file's path to the nav configuration in mkdocs.yml.

Hosting

The guidebook is hosted via GitLab pages. readthedocs.org (RTD) and is automatically deployed on each commit to master. The GitLab pages-managed URL is at https://uis.uniofcam.dev/devops/docs/guidebook/.

To support a custom domain, the guidebook.devops.uis.cam.ac.uk DNS record is a CNAME pointing to uis.uniofcam.dev.io following the custom domain documentation.