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.