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:

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/.

Hosting

The guidebook is hosted as a project on readthedocs.org (RTD) and is automatically built on each commit to master. RTD natively supports mkdocs documentation and so, beyond informing RTD that this is a mkdocs project, no configuration is required to build the docs.

The guidebook.devops.uis.cam.ac.uk DNS record is a CNAME pointing to readthedocs.io following the custom domain documentation from RTD.

Currently, the RTD configuration is manual. To gain access to the project, create a RTD account and ask an existing administrator to add you as a maintainer to the project.

RTD knows when to build the documentation by means of a webhook. This has to be manually added to the Developer Hub project as an integration. The Developer Hub project should be configured to POST to the RTD webhook on push events. GitLab-specific documentation is provided by RTD.