.editorconfig

@@ -3,3 +3,16 @@ root=true
 [*.{html,js,md}]
 indent_size=2
 indent_style=space
+# Keep this in sync with .markdownlint.yaml
+max_line_length=100
+
+[*.{yml,yaml}]
+indent_size=2
+indent_style=space
+
+[*.css]
+indent_size=4
+indent_style=space
+
+[*.py]
+max_line_length=99

.gitignore

+markdown-lint.xml
+
 # PyCharm
 .idea
+site/
+
+# VSCode
+.vscode/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+.DS_Store
+__pycache__/
+
+# build documentation
+public/
+docs/plantuml-diagrams/out/

.gitlab-ci.yml

+include:
+  - project: "uis/devops/continuous-delivery/ci-templates"
+    file: "/pre-commit.yml"
+    ref: v6.7.2
+  - project: "uis/devops/continuous-delivery/ci-templates"
+    file: "/auto-devops-stages.yml"
+    ref: v6.7.2
+
+  # Disable MR pipelines
+  - template: Workflows/Branch-Pipelines.gitlab-ci.yml
+
+# Basic CI to install and run mkdocs build in strict mode with verbose output.
+# We upload the built documentation as an artifact so that it can be browsed
+# from the build jobs.
+test:
+  stage: test
+  image: registry.gitlab.developers.cam.ac.uk/uis/devops/infra/dockerimages/python:alpine
+  services:
+    - name: plantuml/plantuml-server:jetty
+      alias: plantuml
+  before_script:
+    - apk add python3-dev gcc musl-dev
+    - pip install -r requirements.txt
+  script:
+    # We use --no-directory-urls so that the documentation is browsable from the
+    # GitLab artefact browser.
+    - mkdocs build --strict --verbose --site-dir public --no-directory-urls
+    # Expose services.yml for consumption by other apps/services.
+    - mkdir -p public/api
+    - cp data/services.yml public/api/
+    # This is a horrible hack to preserve legacy URLs from RTD. Unfortunately symlinks aren't
+    # supported in GitLab pages which would be a nicer solution.
+    - cp -r public latest
+    - mkdir -p public/en
+    - mv latest public/en/
+    - git tag -l | while read tag; do git checkout $tag && mkdocs build --strict --verbose --site-dir public/en/$tag --no-directory-urls ; done
+    - git checkout master
+  artifacts:
+    expose_as: "Browse the documentation for this MR by following links to public and index html"
+    paths:
+      - public/
+  variables:
+    SITE_URL: "https://uis.uniofcam.dev/-/devops/docs/guidebook/-/jobs/${CI_JOB_ID}/artifacts/public"
+
+markdownlint:
+  stage: test
+  image:
+    # Keep this version number in sync with the one in .pre-commit-config.yaml
+    name: davidanson/markdownlint-cli2:v0.17.2
+    entrypoint: [""]
+  script:
+    - cp mdlint-formatter.jsonc .markdownlint-cli2.jsonc
+    - markdownlint-cli2 "**/*.md" "#node_modules"
+  artifacts:
+    reports:
+      junit: markdown-lint.xml
+
+
+pages:
+  # Just like the "test" build except we enable directory URLs.
+  extends: test
+  stage: production
+  script:
+    - unset SITE_URL # SITE_URL is only used in the test job & inherited from there.
+    - mkdocs build --strict --verbose --site-dir public
+    # Expose services.yml for consumption by other apps/services.
+    - mkdir -p public/api
+    - cp data/services.yml public/api/
+    # This is a horrible hack to preserve legacy URLs from RTD. Unfortunately symlinks aren't
+    # supported in GitLab pages which would be a nicer solution.
+    - cp -r public latest
+    - mkdir -p public/en
+    - mv latest public/en/
+    - git tag -l | while read tag; do git checkout $tag && mkdocs build --strict --verbose --site-dir public/en/$tag --no-directory-urls ; done
+    - git checkout master
+  artifacts:
+    paths:
+      - public
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+    - if: $CI_COMMIT_TAG

.markdownlint.yaml

+default: true
+
+MD007:
+  # Required for the markdown parser used by mkdocs.
+  indent: 4
+
+MD013:
+  # Keep this in sync with .editorconfig
+  line_length: 100
+
+# We allow inline HTML.
+MD033: false
+
+# Some images don't have alt text. Aspire to fix this, but disable in the meantime.
+MD045: false
+
+# Admonitions break the code fence style checker.
+MD046: false
+
+MD025:
+  front_matter_title: "^---\n\\s*title\\s*[:=]\n---"

.pre-commit-config.yaml

+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+        args:
+          - --unsafe
+      - id: check-json
+      - id: check-toml
+      - id: check-xml
+      - id: check-added-large-files
+      - id: check-executables-have-shebangs
+      - id: check-merge-conflict
+      - id: check-symlinks
+      - id: detect-private-key
+        exclude: ^docs/home/contact/openpgp\.min\.js$
+      - id: mixed-line-ending
+      - id: pretty-format-json
+        args:
+          - --autofix
+          - --no-sort-keys
+      - id: debug-statements
+
+  - repo: https://github.com/DavidAnson/markdownlint-cli2
+    # Keep this version number in sync with the one in .gitlab-ci.yml
+    rev: v0.17.2
+    hooks:
+      - id: markdownlint-cli2
+        args: ["--fix"]
+        language_version: 22.10.0

.readthedocs.yaml

+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+   install:
+   - requirements: requirements.txt

Dockerfile

+FROM python:3.13-alpine
+
+RUN apk update && apk add gcc musl-dev git
+
+WORKDIR /workspace/
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+
+# We use git to determine the edit history fo pages to provide a "last updated" timestamp. Work
+# around a git feature which guards against certain types of attacks from untrusted users.
+#
+# More information: https://www.kenmuse.com/blog/avoiding-dubious-ownership-in-dev-containers/
+RUN git config --global --add safe.directory /workspace
+
+CMD ["mkdocs",  "serve", "-a", "0.0.0.0:8000"]

README.md

 # DevOps Guidebook
 
-This repository contains the source for the UIS [DevOps
-Guidebook](https://uisautomation.github.io/guidebook).
+This repository contains the source for the UIS
+[DevOps Guidebook](https://guidebook.devops.uis.cam.ac.uk/)
 
-## Developing locally
+## Hosting
 
-The guidebook uses [docsify](https://docsify.js.org/) to render the guidbook
-from markdown striaght in the browser. As such there is no render step. One
-simply clones the repo and starts a local webserver. If you have the
-[hub](https://github.com/github/hub) utility installed:
+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/](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](https://docs.gitlab.com/ee/user/project/pages/custom_domains_ssl_tls_certification/).
+
+## Local Development
+
+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](https://pre-commit.com/index.html#install)
+and clone the repo locally:
 
 ```console
-$ hub clone uisautomation/guidebook
-$ python3 -m http.server 8000
+git clone git@gitlab.developers.cam.ac.uk:uis/devops/docs/guidebook.git
+pre-commit install
+```
+
+Start the guidebook via:
+
+```console
+docker-compose up --build
+```
+
+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`.
+
+## Service Information
+
+Service & team information is encoded in [services.yml](./data/services.yml).
+
+When adding or updating a Service page, you must update that file to define such information.
+
+Comments in the file itself describe each section's format.
+
+The file is exposed at endpoint `/api/services.yml` for consumption by other apps/services,
+via a script in the [Gitlab CI config](./.gitlab-ci.yml).
+
+**NOTE:**
+
+* The canonical source of DevOps teams and team-service mappings is
+  [this Google Doc][devops-team-structure].
+
+* This YAML configuration simply encodes the information in a machine-parsable format,
+  and must be manually updated to remain in-sync with that document.
+
+## Site-Relative URLs
+
+Site-relative URLs can be specified using `site:path/to/some-page`.
+
+This functionality is provided by a custom [hook][mkdocs-hooks]
+in [hooks/site_urls.py](./hooks/site_urls.py)
+
+These are preferable to relative URLs, since:
+
+* A page containing `site:` URLs needn't change if it's relocated.
+    * Whereas, a page containing relative URLs would need all of them updated.
+* A page referenced by `site:` URLs can be relocated,
+  then a single search-and-replace performed to update all references.
+    * Whereas, a page referenced by different relative URLs
+    requires that they all be updated, and each becomes defferent.
+
+Such `site:` urls are translated as follows,
+depending on whether the code is running locally or in Gitlab CI,
+where flag `--no-directory-urls` is passed to `mkdocs build`:
+
+<!-- markdownlint-disable MD013 -->
+| Example `site:` URL  | Doc Path               | Local URL        | CI Artifact URL<br>with `--no-directory-urls` |
+| -------------------- | ---------------------- | ---------------- | --------------------------------------------- |
+| `site:path/to/page`  | `docs/path/to/page.md` | `/path/to/page/` | `$SITE_ROOT/path/to/page.html`                |
+| `site:path/to/page/` | `docs/path/to/page.md` | `/path/to/page/` | `$SITE_ROOT/path/to/page/index.html`          |
+<!-- markdownlint-enable MD013 -->
+
+## Custom Plugin Syntax
+
+Some MkDocs extensions & plugins used (see [mkdocs.base.yml][mkdocs-config-base])
+provide custom syntax to utilise their new visual elements.
+
+Here's a summary of the custom syntax we utilise, provided by our configured extensions & plugins:
+
+<!-- markdownlint-disable MD013 -->
+| Extension / Plugin                               | Notation                                            | Meaning                                                     |
+| ------------------------------------------------ | --------------------------------------------------- | ----------------------------------------------------------- |
+| [Admonitions][mkdocs-plugin-admonitions]         | `!!! note`, `??? tip`, etc.                         | A styled callout, which may be collapsible                  |
+| [PymdownX > Snippets][mkdocs-plugin-snippets]    | `--8<-- "path/to/file.(md\|ext)"`                   | Insert contents of the specified file.                      |
+| [Neoteroi > Cards][mkdocs-plugin-neoteroi-cards] | `[cards cols=2 smaller(path/to/cards.(json\|yml))]` | Insert the visual cards defined in specified file.          |
+| Site-Relative URLs _(see section below)_         | `site:path/to/some-page`                            | Site-relative URL (in our case `docs/path/to/some-page.md`) |
+<!-- markdownlint-enable MD013 -->
+
+## Macros
+
+The guidebook uses a set of macros to provide a consistent look and feel to the documentation.
+
+Also to auto-generate certain information based on static configuration (`.yml`) files.
+
+The [MkDocs-Macros plugin](https://mkdocs-macros-plugin.readthedocs.io/)
+is used to simplify this process.
+
+* It loads [main.py](./main.py) to access & apply all custom macros.
+* Those are stored within [macros/](./macros/).
+* To add a new macro, either add to or create a file in [macros/<context>.py](./macros/).
+
+### Create a New Template Variable
+
+If you want to add a new template variable,
+simply define it in `TEMPLATE_VARIABLES` within [macros/constants.py](./macros/constants.py).
+
+It will then be available within all `.md` files as `{{ my_variable }}`.
+
+### Create a Macro Mixin
+
+If adding macros for a new context, create a new file `macros/{my-context}.py`:
+
+```python
+from ..render import hyperlink # etc
+
+def define_env(env):
+  env.macro(my_macro)
+  # ..wrap all other macros too..
+
+def my_macro(...):
+  pass # return render result here e.g. hyperlink(...)
 ```
 
-The documentation is now available at http://localhost:8000/.
+Then import and invoke your module's `define_env` in `macros/__init__.py`:
+
+```python
+from . import (..., my_context, ...)
+
+def define_env(env):
+    # ...
+    my_context.define_env(env)
+    # ...
+```
+
+In similar fashion, add to [macros/render](./macros/render)
+any needed context-specific HTML rendering _(see existing examples there)_.
+
+Your macro(s) will then be available within all `.md` files as `{{ my_macro(..args..) }}`.
+
+<!-- markdownlint-disable MD013 -->
+[devops-team-structure]: https://docs.google.com/document/d/1fNkYa5z0vY44aStN_67BjoAn8VJN8mvHhX-iip1y25g/edit#heading=h.gb6gzxjsa2r2
+[mkdocs-plugin-admonitions]: https://squidfunk.github.io/mkdocs-material/reference/admonitions/
+[mkdocs-config-base]: ./mkdocs.base.yml
+[mkdocs-hooks]: https://www.mkdocs.org/user-guide/configuration/#hooks
+[mkdocs-plugin-neoteroi-cards]: https://www.neoteroi.dev/mkdocs-plugins/cards/
+[mkdocs-plugin-snippets]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
+<!-- markdownlint-enable MD013 -->

_sidebar.md

-* Introduction
-
-  * [Front matter](index.md)
-  * [About the guidebook](about.md)
-
-* Development
-
-  * [Bootstrapping](bootstrapping.md)
-  * [Story lifecycle](storylifecycle.md)
-
-* Working Environment
-
-  * [Day-to-day workflow](workflow.md)
-  * [Roles](roles.md)
-
-* Technology
-
-  * [Overview](technology/overview.md)
-  * [React and Django](technology/react.md)
-
-* Best practice
-
-  * [Overview](bestpractice/overview.md)
-  * [Product/component hierarchy](bestpractice/hierarchy.md)
-  * [Web applications](bestpractice/webapps.md)
-  * [Using git](bestpractice/git.md)
-  * [Python](bestpractice/python.md)
-  * [JavaScript](bestpractice/javascript.md)

about.md

-# About this guidebook
-
-This guidebook documents what we as a team in DevOps aspire to be, what we
-currently do and practices we currently find to be helpful.
-
-It is not intended as a prescriptive document but rather to be *descriptive* of
-the general way we do things. If the way we do things and the book disagree, it
-is the book which is usually at fault.
-
-## Updating the guide
-
-Anyone may propose an edit to the guide by [opening a pull
-request](https://github.com/uisautomation/guidebook/pulls). When doing so,
-please try to keep the "voice" of the guide consistent.
-
-There are two audiences for the book:
-
-1. **New starters.** These are people new to the team who are interested in how
-   we work and how to get starting developing our products. This guide should
-   help them discover how our products are structured in general and how we do
-   work day-to-day.
-
-2. **Existing team members.** These are people who have been in the team for a
-   while but who would like a reference for best practice. It also provides a
-   location to record new best practice as it is discovered/evolved.

bestpractice/git.md

-# Using git
-
-This section documents some best practice when using the
-[git](https://git-scm.com/) source code management tool.
-
-Good sources of documentation for git include:
-
-* The [git documentation site](https://git-scm.com/doc) which links to free
-    ebooks and videos about git.
-* Members of UIS have access to LinkedIn Learning which has [many
-    videos](https://www.linkedin.com/learning/me?u=2963594) on git.
-* GitHub maintain [extensive documentation](https://help.github.com/) on their
-    platform and git in general.
-
-## Concepts
-
-This section *very briefly* lists the main concepts in git. There are [gory
-details](https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain) in
-the git book. There is also a [terminology section](#terminology) at the end of
-this document if any of the terms used herein are unknown.
-
-### Pushing and pulling
-
-**Pushing** a branch to a remote consists of two stages:
-
-1. The remote is sent the branch HEAD commit and any parent commits it doesn't
-   already have.
-2. The remote updates the remote branch to point to the new HEAD.
-
-This only happens if the remote branch's original HEAD is a descendent of the
-local branch's HEAD. Otherwise the push fails.
-
-**Pulling** a branch is the opposite of a push. The steps are identical by the
-roles of the remote and local repository are reversed.
-
-### GitHub != git
-
-It is tempting to identify GitHub and git. GitHub is a service provider which
-offers git hosting and a set of related "software forge" functionality such as
-issue tracking, project management, code review, etc. GitHub may be the 800lb
-gorilla of the git world but there are many other large apes out there.
-
-Git was originally designed to be decentralised. It is quite possible to use git
-without GitHub and even without a working Internet connection.
-
-## Feature branches
-
-Feature branches are branches being used to develop an individual story. If you
-are stuck for a name, "issue-{number}-{summary}" is a good choice where
-"{number}" is the issue number of the story you are implementing and "{summary}"
-is a brief summary of the story formatted-like-this.
-
-### Structuring the branch
-
-Tell a story with your branch: each commit should implement one step towards
-implementing the story. It is kind to a reviewer to allow your pull requests to
-be reviewed commit-wise so try to keep commits small, on topic and
-self-contained.
-
-### Commits
-
-Each commit message should start with a single line summarising the change. If
-the repository has logical "sections", start your commit message with the
-section and a colon. For example, a Django webapp is usually composed of several
-applications. Using the application name as a section is a good idea. The
-single-line summary of a commit is, by convention, rather short. Keeping it
-around 50 characters is a good rule of thumb given in the [git
-documentation](https://git-scm.com/docs/git-commit#_discussion).
-
-The commit message proper should explain how the commit implements what it
-implements. It may also explain how the commit fits into the overall progression
-of the story.
-
-If the commit closes an issue, use a [GitHub
-keyword](https://help.github.com/articles/closing-issues-using-keywords/) in the
-commit. If only the pull request as a whole closes the issue, use the keyword in
-the pull-request message.
-
-An example message:
-
-```
-mediaplatform: MediaItem: make channel field non-NULL
-
-Make the "channel" field of mediaplatform.models.MediaItem non-NULL. This
-enforces that all media items will have an associated channel in future which is
-required by #1234.
-
-Add a pre-migration hook which assigns all media items which currently have a
-"NULL" channel to an "orphan" channel. If there are no items with a NULL channel
-the orphan channel is not created.
-
-The orphan channel has blank edit and view permissions and as such will only be
-available to admins.
-
-Closes #1234
-```
-
-### Rebasing
-
-Git [rebasing](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) is an
-invaluable tool to help you structure your branch to be easy to review. When
-developing, the rule is "commit early, commit often". After you have finished
-implementing the feature, you may re-order, combine and re-word commits using
-the ``git rebase`` tool.
-
-!> Once you have shared your branch with others via a pull request, do not
-rebase as it makes pulling your changes harder.
-
-## Terminology
-
-This section briefly describes some of the terminology around git. It's not
-intended to be exhaustive.
-
-A **blob** is a set of bytes. It has a name which is the SHA1 hash of its
-contents.
-
-A **tree** is a set of blobs in a directory/filename hierarchy. It has a name
-which is the SHA1 hash of its contents.
-
-A **commit** is a message describing a tree, the name of a tree and a list of
-names of "parent" commits. Its has a name which is the SHA1 hash of its
-contents. Recursively following parent links from a commit yields the set of
-"descendent" commits.
-
-A **branch** is an alias for a commit. Its content is the name of the commit it
-references. Its name is human-readable. Unlike commits, blobs or trees a
-branch's name can stay the same even if its content changes. The commit pointed
-to by a branch is called the **HEAD** of the branch.
-
-The **master branch** is the branch which we agree as a team reflects the
-current state of the product. Beyond this convention and the fact that it is the
-default checked out branch when a repository is cloned *there is nothing
-special about the master branch**.
-
-A **remote** is an alias for a remote git repository. It maps a human readable
-name to a location. For example,
-"origin"→"git@github.com:uisautomation/guidebook".

bestpractice/hierarchy.md

-# Product/component hierarchy
-
-Each *product* which we develop is usually composed of multiple *components*.
-For example, a web application may have a public repository containing the
-source for the application and a private deployment repository which contains
-scripts and configuration to deploy the web application on our infrastructure.
-
-## Repository naming
-
-Name a new Github repository using the form ``{product}-{component}``. For
-example, the web application for the Media Platform is at
-[uisautomation/media-webapp](https://github.com/uisautomation/media-webapp).
-
-## Filesystem layout
-
-Divide your repositories into a ``{product}/{component}`` hierarchy. Single-repo
-products should be cloned into a separate ``devops`` directory.  For example, if
-you store your cloned repositories in the ``~/repos`` directory and are working
-on the IAR, Media Platform, this guidebook and our boilerplate application, your
-repositories will be cloned as follows:
-
-```
-~/repos
-├── devops
-│   ├── django-boilerplate
-│   └── guidebook
-├── iar
-│   ├── backend
-│   ├── deploy
-│   └── frontend
-└── media
-    ├── deploy
-    └── webapp
-```

bestpractice/python.md

-# Python
-
-The DevOps division are heavy users of the Python programming language
-for backend work.
-
-## Code style
-
-We do not maintain a style guide but [Google's
-guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md) is a good
-starting point.
-
-## flake8
-
-Most of our Python code is set up to automatically check Python code for PEP8
-compliance. We use the default set of rules for flake8 except that we relax the
-maximum line length to 99 characters. (This being the maximum allowed by PEP8.)
-
-## Testing
-
-Use unit testing to check functionality of code. Sometimes, the use of
-[doctest](https://docs.python.org/3/library/doctest.html) is useful for
-functions which are private to a module. Generally, we use the Django test
-runner provided by the boilerplate application.
-
-## Code coverage
-
-Test code coverage is reported in most of our code and a minimal code coverage
-level is enforced for most of our repositories. New code should usually be
-accompanied by tests which exercise the code.

bootstrapping.md

-# Bootstrapping
-
-This section has some general guidance on how you can get started developing
-applications for us. We assume a working knowledge of git and Unix-like
-operating systems.
-
-?> UIS members may gain such a knowledge through our [LinkedIn
-Learning](https://www.linkedin.com/learning/) organisational account.
-
-## GitHub account
-
-The majority of our products are developed on GitHub. When you join the DevOps
-team you will be asked for your GitHub account name. You may wish to use a
-personal account or create one named after your crsid.
-
-### Add a SSH public key
-
-The git version control system works best when used in combination with SSH. You
-will want to [associate a SSH key with your
-account](https://github.com/settings/keys).
-
-?> For more information, see the [GitHub documentation on
-SSH](https://help.github.com/articles/connecting-to-github-with-ssh/).
-
-### Configure GitHub
-
-GitHub has a notification system which can be used to notify you over email when
-things of interest happen. Having notifications enabled is useful to keep you in
-the loop as any changes you make are reviewed, commented on and, eventually,
-merged. You can [configure
-notifications](https://github.com/settings/notifications) in the GitHub
-settings.
-
-## Clone product repositories
-
-The usual naming convention for repositories is ``{product}-{component}``. For
-example, the web application for the Media Platform is at
-[uisautomation/media-webapp](https://github.com/uisautomation/media-webapp).
-
-?> Having your repository cloned to a matching ``{product}/{component}``
-directory is considered [best
-practice](bestpractice/hierarchy.md#filesystem-layout).
-
-If you install [hub](https://hub.github.com/), you can clone a local repository
-and create your own fork:
-
-```bash
-$ cd ~/repos  # or, wherever you keep your clones repositories
-$ mkdir media && cd media
-$ hub clone uisautomation/media-webapp webapp && cd webapp
-$ hub fork  # creates a fork and adds a new remote
-```
-
-## Configure CircleCI for your fork
-
-Most of our products use [CircleCI](https://circleci.com/) for continuous
-integration and development. You can set up CircleCI integration for your fork
-by visiting https://circleci.com/gh/{username}/{repository} in your browser and
-clicking the "Follow Project" button.
-
-For example, to configure [bb9e](https://github.com/bb9e)'s fork of
-[iar-backend](https://github.com/uisautomation/iar-backend), visit
-https://circleci.com/gh/bb9e/iar-backend.
-
-## Read the documentation
-
-The README file in a repository will contain any special information about
-getting started with a project. For example, you may need to obtain and
-configure some product-specific credentials. This file may also contain any
-CircleCI specific configuration you require for your fork.
-
-?> From the repository root directory, you can open the corresponding GitHub
-repository web page and read the README file using the command
-``hub browse``.
-
-## Webapps
-
-This section is specific to getting started developing our webapps.
-
-For webapps, we have settled on a solution for local development based on
-[docker-compose](https://docs.docker.com/compose/). This allows for a consistent
-development environment even if an individual Developer's machine varies.
-
-### Configure Codecov for your fork
-
-Many of our products use [Codecov](https://codecov.io/) for code coverage
-checking. You can set up Codecov integration for your fork
-by visiting https://codecov.io/gh/{username}/{repository} in your browser.
-
-For example, to configure [bb9e](https://github.com/bb9e)'s fork of
-[iar-backend](https://github.com/uisautomation/iar-backend), visit
-https://codecov.io/gh/bb9e/iar-backend.
-
-### Install Docker and docker-compose
-
-Make sure that the latest version of [docker](https://www.docker.com/) and
-docker-compose are installed on your machine. Using docker-compose allows us to
-run tests and develop within an environment very close to that we deploy in.
-
-### Run tests
-
-Tests for the webapp can be run inside a container using the ``./tox.sh`` script
-present in many of our webapps. Generally this will check that the documentation
-builds, run code style checks and run the test suite. A code coverage summary
-will be shown after the tests run.
-
-### Start a development server
-
-A development server can be started with ``./compose.sh development up``. The
-web application is then usually available at http://localhost:8000/.
-
-For applications making use of React to render the frontend, we usually have
-automatically generated
-[styleguidist](https://github.com/styleguidist/react-styleguidist) documentation
-for React components at http://localhost:6060/.
-
-For applications which send email, we usually have a
-[MailHog](https://github.com/mailhog/MailHog) instance running at
-http://localhost:8025.
-
-## Deployment
-
-!> This section is likely to change significantly.
-
-We deploy applications using configuration in a ``{product}-deploy`` repository
-on GitHub. Usually these repositories are private. See the ``README`` in any one
-repository for an overview of how deployment happens for that product.

compose/jetty-logging.properties

+## Set logging levels from: ALL, TRACE, DEBUG, INFO, WARN, ERROR, OFF
+org.eclipse.jetty.LEVEL=ERROR

data/README.md

+# Static data
+
+This directory contains static data used by the guidebook.
+
+## Labels
+
+The `labels.yml` file contains GitLab label definitions for the [uis/devops
+group](https://gitlab.developers.cam.ac.uk/uis/devops) in GitLab. It was
+generated using the following command line which uses
+[httpie](https://httpie.io/) and [yq](https://mikefarah.gitbook.io/yq/):
+
+<!-- markdownlint-disable MD013 -->
+```sh
+http "https://gitlab.developers.cam.ac.uk/api/v4/groups/uis%2Fdevops/labels?per_page=100" "PRIVATE-TOKEN:$TOKEN" | yq eval -P > labels.yml
+```
+<!-- markdownlint-enable MD013 -->
+
+You should arrange for the `TOKEN` environment variable to contain a [GitLab
+personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)
+with at least the `read_api` scope.

data/labels.yml

+- id: 2690
+  name: Accessibility
+  description: null
+  description_html: ""
+  text_color: '#FFFFFF'
+  color: '#0033CC'
+  subscribed: false
+- id: 2377
+  name: Business Analysis
+  description: 'Issues which ask questions about an existing business process or which require the development of a new one '
+  description_html: 'Issues which ask questions about an existing business process or which require the development of a new one '
+  text_color: '#FFFFFF'
+  color: '#0033CC'
+  subscribed: false
+- id: 992
+  name: chore
+  description: Issues where the work required is "straightforward" (such as fixing typos, manually configuring a service), usually time-boxed to half-a-day
+  description_html: Issues where the work required is "straightforward" (such as fixing typos, manually configuring a service), usually time-boxed to half-a-day
+  text_color: '#FFFFFF'
+  color: '#AD4363'
+  subscribed: false
+- id: 5640
+  name: Comms Required
+  description: Communication required to release feature
+  description_html: Communication required to release feature
+  text_color: '#333333'
+  color: '#f3edb3'
+  subscribed: false
+- id: 993
+  name: dependency
+  description: ""
+  description_html: ""
+  text_color: '#333333'
+  color: '#A295D6'
+  subscribed: false
+- id: 541
+  name: design needed
+  description: Issues which cannot be addressed without some design work being carried out
+  description_html: Issues which cannot be addressed without some design work being carried out
+  text_color: '#FFFFFF'
+  color: '#FF0000'
+  subscribed: false
+- id: 6385
+  name: Developer Experience
+  description: Issue relates to developer tooling or documentation
+  description_html: Issue relates to developer tooling or documentation
+  text_color: '#FFFFFF'
+  color: '#0033cc'
+  subscribed: false
+- id: 2229
+  name: Development
+  description: Issues which require active software or infrastructure-as-code development work
+  description_html: Issues which require active software or infrastructure-as-code development work
+  text_color: '#FFFFFF'
+  color: '#0033CC'
+  subscribed: false
+- id: 1227
+  name: discussion
+  description: Issues which primarily contain or require a discussion rather than a task
+  description_html: Issues which primarily contain or require a discussion rather than a task
+  text_color: '#333333'
+  color: '#A295D6'
+  subscribed: false
+- id: 2493
+  name: Documentation
+  description: Issues which require writing documentation for the team or end users
+  description_html: Issues which require writing documentation for the team or end users
+  text_color: '#FFFFFF'
+  color: '#0033CC'
+  subscribed: false
+- id: 5806
+  name: EpicType::Epic
+  description: The most detailed type of epic - issues are attached to epics at this level
+  description_html: The most detailed type of epic - issues are attached to epics at this level
+  text_color: '#FFFFFF'
+  color: '#33b3a6'
+  subscribed: false
+- id: 5833
+  name: EpicType::Feature
+  description: Mid-level epic
+  description_html: Mid-level epic
+  text_color: '#FFFFFF'
+  color: '#33b3a6'
+  subscribed: false
+- id: 5805
+  name: EpicType::Initiative
+  description: Used for grouping detailed epics for easier management
+  description_html: Used for grouping detailed epics for easier management
+  text_color: '#FFFFFF'
+  color: '#33b3a6'
+  subscribed: false
+- id: 6345
+  name: EpicType::Placeholder
+  description: To capture anticipated work while allowing it to be filtered out of epic lists/boards
+  description_html: To capture anticipated work while allowing it to be filtered out of epic lists/boards
+  text_color: '#FFFFFF'
+  color: '#33b3a6'
+  subscribed: false
+- id: 1224
+  name: good first issue
+  description: ""
+  description_html: ""
+  text_color: '#FFFFFF'
+  color: '#F0AD4E'
+  subscribed: false
+- id: 1146
+  name: incomplete
+  description: Issue is incomplete and needs its description improving
+  description_html: Issue is incomplete and needs its description improving
+  text_color: '#FFFFFF'
+  color: '#FF0000'
+  subscribed: false
+- id: 2686
+  name: issueType::Bug
+  description: Functionality of product is not as designed or intended by the code author
+  description_html: Functionality of product is not as designed or intended by the code author
+  text_color: '#FFFFFF'
+  color: '#c21e56'
+  subscribed: false
+- id: 4859
+  name: issuetype::Epic
+  description: null
+  description_html: ""
+  text_color: '#FFFFFF'
+  color: '#00b140'
+  subscribed: false
+- id: 6027
+  name: issuetype::Feedback
+  description: For feedback on the system provided by users
+  description_html: For feedback on the system provided by users
+  text_color: '#FFFFFF'
+  color: '#cc338b'
+  subscribed: false
+- id: 5538
+  name: issuetype::Support
+  description: ""
+  description_html: ""
+  text_color: '#FFFFFF'
+  color: '#00b140'
+  subscribed: false
+- id: 4857
+  name: issuetype::Task
+  description: null
+  description_html: ""
+  text_color: '#FFFFFF'
+  color: '#00b140'
+  subscribed: false
+- id: 5254
+  name: issuetype::Theme
+  description: This is a large collection of work, comprised of one or more epics
+  description_html: This is a large collection of work, comprised of one or more epics
+  text_color: '#FFFFFF'
+  color: '#00b140'
+  subscribed: false
+- id: 4858
+  name: issuetype::User Story
+  description: An end-to-end user-centric piece of work sized to fit within a single sprint
+  description_html: An end-to-end user-centric piece of work sized to fit within a single sprint
+  text_color: '#FFFFFF'
+  color: '#00b140'
+  subscribed: false
+- id: 5202
+  name: Lookup
+  description: Issues relating to Lookup
+  description_html: Issues relating to Lookup
+  text_color: '#FFFFFF'
+  color: '#36454f'
+  subscribed: false
+- id: 4190
+  name: Meeting
+  description: Issue represents a meeting where a decision needs to be made.
+  description_html: Issue represents a meeting where a decision needs to be made.
+  text_color: '#FFFFFF'
+  color: '#0033CC'
+  subscribed: false
+- id: 5013
+  name: meeting::backlog refinement
+  description: ""
+  description_html: ""
+  text_color: '#FFFFFF'
+  color: '#eee600'
+  subscribed: false
+- id: 5024
+  name: meeting::sprint planning
+  description: ""
+  description_html: ""
+  text_color: '#FFFFFF'
+  color: '#eee600'
+  subscribed: false
+- id: 5705
+  name: mob programming
+  description: This issue is intended for "mob programming" team effort (https://en.wikipedia.org/wiki/Mob_programming)
+  description_html: This issue is intended for "mob programming" team effort (<a href="https://en.wikipedia.org/wiki/Mob_programming" rel="nofollow noreferrer noopener" target="_blank">https://en.wikipedia.org/wiki/Mob_programming</a>)
+  text_color: '#FFFFFF'
+  color: '#8fbc8f'
+  subscribed: false
+- id: 2295
+  name: moodle
+  description: Issues which relate to the Moodle Cloud project
+  description_html: Issues which relate to the Moodle Cloud project
+  text_color: '#FFFFFF'
+  color: '#36454f'
+  subscribed: false
+- id: 2230
+  name: Operations
+  description: Issues which relate to deployment or packaging of products
+  description_html: Issues which relate to deployment or packaging of products
+  text_color: '#FFFFFF'
+  color: '#0033CC'
+  subscribed: false
+- id: 2014
+  name: placeholder
+  description: Issues which arose during the sprint and were not present at the beginning
+  description_html: Issues which arose during the sprint and were not present at the beginning
+  text_color: '#FFFFFF'
+  color: '#5843AD'
+  subscribed: false
+- id: 2929
+  name: Pooled Testing
+  description: null
+  description_html: ""
+  text_color: '#FFFFFF'
+  color: '#36454f'
+  subscribed: false
+- id: 4882
+  name: priority::0 Highest
+  description: null
+  description_html: ""
+  text_color: '#FFFFFF'
+  color: '#ff0000'
+  subscribed: false
+- id: 2459
+  name: priority::1 High
+  description: null
+  description_html: ""
+  text_color: '#FFFFFF'
+  color: '#FF0000'
+  subscribed: false
+- id: 2460
+  name: priority::2 Medium
+  description: null
+  description_html: ""
+  text_color: '#FFFFFF'
+  color: '#F0AD4E'
+  subscribed: false
+- id: 2461
+  name: priority::3 Low
+  description: null
+  description_html: ""
+  text_color: '#FFFFFF'
+  color: '#D1D100'
+  subscribed: false
+- id: 2739
+  name: priority::4 Lowest
+  description: null
+  description_html: ""
+  text_color: '#FFFFFF'
+  color: '#5CB85C'
+  subscribed: false
+- id: 1087
+  name: question
+  description: A question has been asked that will determine if rework is required
+  description_html: A question has been asked that will determine if rework is required
+  text_color: '#FFFFFF'
+  color: '#D10069'
+  subscribed: false
+- id: 1097
+  name: quick to review
+  description: Issues whose MRs are small changes or which are otherwise easy to review
+  description_html: Issues whose MRs are small changes or which are otherwise easy to review
+  text_color: '#333333'
+  color: '#A8D695'
+  subscribed: false
+- id: 4633
+  name: 'resolution:: Can''t Reproduce'
+  description: Can't reproduce the bug/issue
+  description_html: Can't reproduce the bug/issue
+  text_color: '#FFFFFF'
+  color: '#c21e56'
+  subscribed: false
+- id: 4634
+  name: 'resolution:: DevNotPlanned'
+  description: null
+  description_html: ""
+  text_color: '#FFFFFF'
+  color: '#c21e56'
+  subscribed: false
+- id: 4632
+  name: 'resolution:: Duplicate'
+  description: Duplicate of an existing bug/issue
+  description_html: Duplicate of an existing bug/issue
+  text_color: '#FFFFFF'
+  color: '#c21e56'
+  subscribed: false
+- id: 5948
+  name: resolution::Fixed
+  description: Fixed bug.
+  description_html: Fixed bug.
+  text_color: '#FFFFFF'
+  color: '#c21e56'
+  subscribed: false
+- id: 1216
+  name: 'resolution:: Won''t Fix'
+  description: Not actually a bug or beyond a reasonable to fix
+  description_html: Not actually a bug or beyond a reasonable to fix
+  text_color: '#FFFFFF'
+  color: '#c21e56'
+  subscribed: false
+- id: 6118
+  name: Service Wrapper
+  description: null
+  description_html: ""
+  text_color: '#FFFFFF'
+  color: '#6699cc'
+  subscribed: false
+- id: 148
+  name: small change
+  description: ""
+  description_html: ""
+  text_color: '#FFFFFF'
+  color: '#8E44AD'
+  subscribed: false
+- id: 991
+  name: spike
+  description: Tasks which are time-boxed to one day
+  description_html: Tasks which are time-boxed to one day
+  text_color: '#FFFFFF'
+  color: '#0033CC'
+  subscribed: false
+- id: 2378
+  name: Support
+  description: Issues relating to an end-user support request (such as changing user permissions or fixing incorrect data)
+  description_html: Issues relating to an end-user support request (such as changing user permissions or fixing incorrect data)
+  text_color: '#FFFFFF'
+  color: '#0033CC'
+  subscribed: false
+- id: 4831
+  name: team::Authentication
+  description: null
+  description_html: ""
+  text_color: '#FFFFFF'
+  color: '#330066'
+  subscribed: false
+- id: 4830
+  name: team::Cloud
+  description: ""
+  description_html: ""
+  text_color: '#FFFFFF'
+  color: '#330066'
+  subscribed: false
+- id: 2928
+  name: team::DevOps
+  description: Issues which are likely to be picked up by the DevOps team
+  description_html: Issues which are likely to be picked up by the DevOps team
+  text_color: '#FFFFFF'
+  color: '#330066'
+  subscribed: false
+- id: 4587
+  name: team::Identity
+  description: null
+  description_html: ""
+  text_color: '#FFFFFF'
+  color: '#330066'
+  subscribed: false
+- id: 2381
+  name: Testing
+  description: Issues which involve automated or manual testing as the primary aim
+  description_html: Issues which involve automated or manual testing as the primary aim
+  text_color: '#FFFFFF'
+  color: '#0033CC'
+  subscribed: false
+- id: 2379
+  name: UI Design
+  description: 'Issues which require user interface design work '
+  description_html: 'Issues which require user interface design work '
+  text_color: '#FFFFFF'
+  color: '#0033CC'
+  subscribed: false
+- id: 706
+  name: urgent
+  description: ""
+  description_html: ""
+  text_color: '#FFFFFF'
+  color: '#FF0000'
+  subscribed: false
+- id: 1877
+  name: user acceptance testing
+  description: Issue arose as a result of user acceptance testing
+  description_html: Issue arose as a result of user acceptance testing
+  text_color: '#FFFFFF'
+  color: '#D9534F'
+  subscribed: false
+- id: 2380
+  name: UX Research
+  description: 'Issues which require research into user experience '
+  description_html: 'Issues which require research into user experience '
+  text_color: '#FFFFFF'
+  color: '#0033CC'
+  subscribed: false
+- id: 6406
+  name: Wack-a-mole Wednesday
+  description: To flag issues suitable for a day blitz
+  description_html: To flag issues suitable for a day blitz
+  text_color: '#333333'
+  color: '#ffeb44'
+  subscribed: false
+- id: 5512
+  name: workflow::BAU Blocked
+  description: BAU work which has stalled due to external ussue
+  description_html: BAU work which has stalled due to external ussue
+  text_color: '#FFFFFF'
+  color: '#c39953'
+  subscribed: false
+- id: 84
+  name: workflow::Blocked
+  description: This cannot proceed because of external restrictions
+  description_html: This cannot proceed because of external restrictions
+  text_color: '#FFFFFF'
+  color: '#ff0000'
+  subscribed: false
+- id: 4824
+  name: workflow::Done
+  description: Issue meets the Definition of Done
+  description_html: Issue meets the Definition of Done
+  text_color: '#FFFFFF'
+  color: '#009966'
+  subscribed: false
+- id: 150
+  name: workflow::In Progress
+  description: Currently under development
+  description_html: Currently under development
+  text_color: '#FFFFFF'
+  color: '#5CB85C'
+  subscribed: false
+- id: 5329
+  name: workflow::In Testing
+  description: Currently being tested
+  description_html: Currently being tested
+  text_color: '#FFFFFF'
+  color: '#c39953'
+  subscribed: false
+- id: 82
+  name: workflow::Needs Deployment
+  description: Changed need deployment to Production
+  description_html: Changed need deployment to Production
+  text_color: '#FFFFFF'
+  color: '#428BCA'
+  subscribed: false
+- id: 2356
+  name: workflow::Needs Refinement
+  description: The issue requires refining to meet the Definition of Ready
+  description_html: The issue requires refining to meet the Definition of Ready
+  text_color: '#FFFFFF'
+  color: '#7F8C8D'
+  subscribed: false
+- id: 5636
+  name: workflow::Needs Sizing
+  description: An issue that has been refined but needs an estimate on how long it will take in order to meet the Definition of Ready
+  description_html: An issue that has been refined but needs an estimate on how long it will take in order to meet the Definition of Ready
+  text_color: '#333333'
+  color: '#f7e7ce'
+  subscribed: false
+- id: 81
+  name: workflow::Review Required
+  description: This MR is ready to be reviewed by another developer.
+  description_html: This MR is ready to be reviewed by another developer.
+  text_color: '#FFFFFF'
+  color: '#69D100'
+  subscribed: false
+- id: 83
+  name: workflow::Rework
+  description: There are issues with this MR which need resolving
+  description_html: There are issues with this MR which need resolving
+  text_color: '#FFFFFF'
+  color: '#eee600'
+  subscribed: false
+- id: 1600
+  name: workflow::Sprint Ready
+  description: Meets the Definition of Ready
+  description_html: Meets the Definition of Ready
+  text_color: '#FFFFFF'
+  color: '#F0AD4E'
+  subscribed: false

data/services.yml

+---
+
+portfolios:
+  business:
+    title: Business
+  education:
+    title: Education
+  generic:
+    title: Generic Services
+  research:
+    title: Research
+
+service_categories:
+  business:
+    title: Business Systems
+  cloud:
+    title: Cloud and Platforms
+  education:
+    title: Education Services
+  finance:
+    title: Finance
+  generic:
+    title: Generic
+  hr:
+    title: HR
+  iam:
+    title: Identity and Access Management (IAM)
+  intranet:
+    title: Intranet Services
+  other:
+    title: Other
+  postgraduate:
+    title: Postgraduate
+  shared:
+    title: Shared Web Tech
+  recruitment:
+    title: Recruitment
+  research:
+    title: Research Admin
+  teaching:
+    title: Teaching and Learning
+  undergraduate:
+    title: Undergraduate
+  web:
+    title: Web Services
+
+
+# Each entry here is of the form:
+#
+# <team-key>:
+#   title: <team-title>
+#   shorthand: <team-shorthand>
+#   email: <team-email>
+#   lead: <team-lead>
+#
+# Only title & email are mandatory.
+teams:
+  cloud:
+    title: Cloud Team
+    email: cloud@uis.cam.ac.uk
+    lead: ad2139
+    lookup_id: "105531"
+    portfolio: generic
+  devex:
+    title: Developer Experience Team
+    shorthand: DevEx
+    email: devops-devex@uis.cam.ac.uk
+    lead: rjw57
+    portfolio: generic
+  drupal:
+    title: Drupal Team
+    email: drupal@uis.cam.ac.uk
+    lead: jag212
+    portfolio: generic
+  hamilton:
+    title: Hamilton Team
+    email: devops-hamilton@uis.cam.ac.uk
+    lead: bs461
+    portfolio: education
+  holberton:
+    title: Holberton Team
+    email: devops-holberton@uis.cam.ac.uk
+    lead: wgd23
+    portfolio: business
+  hopper:
+    title: Hopper Team
+    email: devops-hopper@uis.cam.ac.uk
+    lead: bs461
+    portfolio: education
+  jackson:
+    title: Jackson Team
+    email: devops-jackson@uis.cam.ac.uk
+    lead: nb745
+    portfolio: generic
+  johnson:
+    title: Johnson Team
+    email: devops-johnson@uis.cam.ac.uk
+    portfolio: research
+  lovelace:
+    title: Lovelace Team
+    email: devops-lovelace@uis.cam.ac.uk
+    lead: snr21
+    portfolio: education
+  wilson:
+    title: Wilson Team
+    email: devops-wilson@uis.cam.ac.uk
+    lead: ek599
+    portfolio: generic
+
+# Each entry here is of the form:
+#
+# <service-key>:
+#   title: <service-page-title>
+#   product-manager: <crs-id>
+#   service-owner: <crs-id>
+#   service-manager: <crs-id>
+#   tech-lead: <crs-id>
+#   teams:
+#     - <team-key>
+#     - ...
+#   engineers:
+#     - <operational engineer crs-id>
+#     - ...
+#
+# The '<service-key>' must match a filename in 'docs/services'
+#   e.g. 'my-service:' implies 'docs/services/my-service.md' exists.
+#
+# Any referenced '<team-key>' must be defined in the 'teams' section below.
+#
+# The only mandatory sub-key is 'title'.
+services:
+
+  acp-12-submission-portal:
+    category: hr
+    title: Academic Career Pathways Grade 12 (ACP-12) Submission Portal
+    service-owner: drb58
+    teams:
+      - holberton
+    engineers:
+      - jl364
+      - wgd23
+      - prb34
+      - az330
+
+  activate-account:
+    category: iam
+    title: Activate Account Service
+    service-owner: nrt33
+    teams:
+      - wilson
+
+  ada:
+    category: business
+    title: ADA for Disability Office
+    service-owner: meh37
+    teams:
+      - jackson
+
+  api-gateway:
+    category: cloud
+    title: API Gateway
+    tech-lead: rjg21
+    teams:
+      - cloud
+      - devex
+      - wilson
+    engineers:
+      - dkh21
+
+  budget-calculator:
+    category: research
+    title: Budget Calculator
+    tech-lead: meh37
+    teams:
+      - johnson
+
+  caias:
+    category: recruitment
+    title: Colleges and Affiliated Institutions Advertising System (CAIAS)
+    service-manager: ajc322
+    teams:
+      - holberton
+    engineers:
+      - wgd23
+
+  camdata:
+    category: education
+    title: Cambridge Data (CamData)
+    teams:
+      - jackson
+    engineers:
+      - dkh21
+      - jag212
+      - jl364
+      - mh2215
+
+  card-management-system:
+    category: iam
+    title: Card Management System
+    tech-lead: av603
+    teams:
+      - wilson
+    engineers:
+      - rjg21
+      - sdw37
+      - dkh21
+
+  claims-management-system:
+    category: research
+    title: Claims Management System (CMS)
+    tech-lead: meh37
+    teams:
+      - johnson
+
+  covid-pooled-testing:
+    category: other
+    title: Covid-19 Testing Pools Management
+    service-owner: jh535
+    service-manager: rjw57
+    tech-lead: rjg21
+    engineers:
+      - sdw37
+      - si202
+
+  data-backup:
+    category: cloud
+    title: Data Backup Service
+    service-owner: amc203
+    service-manager: ad2139
+    tech-lead: rh841
+    teams:
+      - cloud
+    engineers:
+      - rh841
+      - si202
+      - rk725
+      - du228
+      - sdw37
+
+  # Outlier - page lists "project leads" and "work-stream lead"
+  design-system:
+    category: other
+    title: Design System
+    tech-lead: rp431
+    engineers:
+      - rp431
+
+  digital-pooling:
+    category: undergraduate
+    title: Digital Pooling
+    product-manager: bmd42
+    service-owner: hr244
+    service-manager: soj23
+    team-lead: ek599
+    tech-lead: amh254
+    teams:
+      - hopper
+    engineers:
+      - hwtb2
+      - jb2595
+      - pfk22
+
+  web-platform:
+    category: web
+    title: Web Platform (Drupal)
+    teams:
+     - drupal
+
+  eduroam-tokens:
+    category: iam
+    title: Network Access Tokens Service
+    service-owner: rcf34
+    tech-lead: prb34
+    teams:
+      - wilson
+    engineers:
+      - si202
+      - sdw37
+      - ad2139
+
+  equipshare:
+    category: research
+    title: Equipment Sharing
+    teams:
+      - johnson
+    engineers:
+      - ao475
+
+  essm-sync:
+    category: teaching
+    title: Education Space Scheduling and Modelling Sync
+    service-manager: nik22
+    tech-lead: rjg21
+    teams:
+      - hamilton
+
+  events:
+    category: shared
+    title: Events System
+    teams:
+      - jackson
+
+  examoffice:
+    category: education
+    title: Exam Office exam time monitoring
+    engineers:
+      - jl364
+
+  gaobase:
+    category: postgraduate
+    title: Graduate Admissions Course Database (GAOBase)
+    teams:
+      - lovelace
+    engineers:
+      - ad2139
+      - rh841
+      - rk725
+      - sdw37
+      - si202
+
+  gates-trust:
+    category: other
+    title: Gates Trust Admin Tool
+    tech-lead: meh37
+    teams:
+      - jackson
+
+  gates-trust-selection-module:
+    category: other
+    title: Gates Cambridge Trust - Selection Module (GCT/SM)
+    tech-lead: jl364
+    teams:
+      - jackson
+    engineers:
+      - jl364
+
+  gitlab:
+    category: cloud
+    title: GitLab service for the Developers' Hub
+    service-owner: amc203
+    service-manager: rjw57
+    tech-lead: rjw57
+    teams:
+      - cloud
+      - devex
+    engineers:
+      - ad2139
+      - rh841
+      - si202
+      - rk725
+      - du228
+      - sdw37
+
+  governance:
+    category: intranet
+    title: Governance
+    teams:
+      - jackson
+    engineers:
+      - dj257
+      - jl364
+
+  gsuite:
+    category: cloud
+    title: Google Workspace for Education @ Cambridge
+    teams:
+      - wilson
+    engineers:
+      - rjg21
+
+  gsuite-preferences:
+    category: iam
+    title: Google Workspace Preferences App
+    service-owner: amc203
+    tech-lead: rjg21
+    teams:
+      - wilson
+    engineers:
+      - rjw57
+      - rjg21
+
+  hr-integration-app:
+    category: hr
+    title: HR Integration App
+    service-manager: ajc322
+    tech-lead: az330
+    teams:
+      - holberton
+    engineers:
+      - prb34
+      - du228
+      - wgd23
+
+  hta:
+    category: other
+    title: Human Tissue Tracker
+    tech-lead: prb34
+    teams:
+      - holberton
+    engineers:
+      - si202
+      - sdw37
+      - ad2139
+      - prb34
+
+  iam-overview:
+    category: iam
+    title: Identity and Access Management
+    teams:
+      - wilson
+
+  information-asset-register:
+    category: business
+    title: Information Asset Register
+    service-owner: jak59
+    teams:
+      - jackson
+    engineers:
+      - rjg21
+
+  integrated-reward-system:
+    category: hr
+    title: Integrated Reward System (IRS)
+    service-manager: ajc322
+    tech-lead: prb34
+    teams:
+      - holberton
+    engineers:
+      - az330
+      - wgd23
+      - av603
+
+  interfacer:
+    category: research
+    title: Interfacer for Research Systems Team
+    tech-lead: meh37
+    teams:
+      - johnson
+
+  jackdaw:
+    category: iam
+    title: Jackdaw
+    service-owner: vkhs1
+    service-manager: ukd20
+    teams:
+      - wilson
+    engineers:
+      - rjw57
+      - rjg21
+      - ad2139
+      - sdw37
+      - si202
+
+  job-opportunities:
+    category: recruitment
+    title: Job Opportunities
+    service-owner: et305
+    service-manager: ajc322
+    tech-lead: wgd23
+    teams:
+      - holberton
+    engineers:
+      - av603
+
+  lab-allocator:
+    category: teaching
+    title: Lab Allocator
+    teams:
+      - hamilton
+    engineers:
+      - ek599
+      - db947
+
+  lecture-capture-preferences:
+    category: teaching
+    title: Lecture Capture Preferences App
+    teams:
+      - hamilton
+    service-manager: amc203
+    engineers:
+      - rjw57
+      - rjg21
+
+  legacy-application-backups:
+    category: other
+    title: Legacy application backups
+
+  legacy-card-db:
+    category: iam
+    title: Legacy Card System
+    tech-lead: av603
+    teams:
+      - wilson
+    engineers:
+      - rjg21
+      - sdw37
+      - si202
+
+  legacy-nst-ia-labs:
+    category: teaching
+    title: Legacy NST IA Lab Allocation
+
+  lookup-gitlab-sync:
+    category: cloud # ..maybe iam in future
+    title: Lookup To GitLab Sync
+    service-owner: amc203
+    service-manager: ad2139
+    tech-lead: rh841
+    engineers:
+      - rh841
+      - si202
+      - rk725
+      - du228
+      - sdw37
+
+  lookup:
+    category: iam
+    title: Lookup
+    tech-lead: rjg21
+    teams:
+      - wilson
+    engineers:
+      - ad2139
+      - dkh21
+      - sdw37
+      - si202
+
+  malware-and-virus-scanner:
+    category: other
+    title: Malware & Virus Scanner (MVS)
+    tech-lead: mh2215
+    teams:
+      - jackson
+
+  my-cambridge-application:
+    category: undergraduate
+    title: My Cambridge Application
+    service-owner: hr244
+    product-manager: bmd42
+    service-manager: soj23
+    team-lead: ek599
+    tech-lead: amh254
+    teams:
+      - hopper
+    engineers:
+      - hwtb2
+      - jb2595
+      - pfk22
+
+  nursery-waiting-list:
+    category: generic
+    title: Nursery Waiting List
+    tech-lead: meh37
+    teams:
+      - jackson
+
+  panel:
+    category: postgraduate
+    title: Panel
+    tech-lead: meh37
+    teams:
+      - lovelace
+
+  panopto-deployment:
+    category: teaching
+    title: Panopto Deployment
+
+  passwords:
+    category: iam
+    title: Password Management
+    service-owner: vkhs1
+    tech-lead: rjg21
+    teams:
+      - wilson
+    engineers:
+      - ad2139
+      - si202
+      - prb34
+      - sdw37
+
+  postbox:
+    category: hr
+    title: PostBox
+    service-manager: ajc322
+    tech-lead: wgd23
+    teams:
+      - holberton
+    engineers:
+      - av603
+
+  raven-metadata:
+    category: iam
+    title: Shibboleth Metadata Administration service
+    service-owner: vkhs1
+    tech-lead: rjg21
+    teams:
+      - wilson
+    engineers:
+      - amc203
+
+  raven-oauth:
+    category: iam
+    title: Raven OAuth2
+    service-owner: vkhs1
+    tech-lead: rjg21
+    teams:
+      - wilson
+    engineers:
+      - amc203
+      - rjg21
+      - sdw37
+
+  raven-saml2-shim:
+    category: iam
+    title: Raven Webauth to SAML2 Shim
+    service-owner: vkhs1
+    tech-lead: rjg21
+    teams:
+      - wilson
+    engineers:
+      - rjg21
+      - mk2155
+
+  raven-shibboleth:
+    category: iam
+    title: Raven SAML2
+    service-owner: vkhs1
+    tech-lead: rjg21
+    teams:
+      - wilson
+    engineers:
+      - amc203
+      - rjg21
+      - sdw37
+      - si202
+
+  raven-stats:
+    category: iam
+    title: Raven Device Statistics API
+    teams:
+      - wilson
+
+  raven-ucamwebauth:
+    category: iam
+    title: Raven UCamWebAuth
+    service-owner: vkhs1
+    tech-lead: rjg21
+    teams:
+      - wilson
+    engineers:
+      - amc203
+      - rjg21
+      - sdw37
+
+  rco-database:
+    category: research
+    title: RCO Database
+    tech-lead: meh37
+    teams:
+      - johnson
+
+  recruitment-administration-system:
+    category: recruitment
+    title: Recruitment Administration System (RAS)
+    service-manager: ajc322
+    tech-lead: az330
+    teams:
+      - holberton
+    engineers:
+      - prb34
+      - du228
+      - wgd23
+
+  ref-portals:
+    category: research
+    title: Research Excellence Framework (REF) portals
+    teams:
+      - johnson
+    engineers:
+      - jl364
+
+  regent-house-ballots:
+    category: generic
+    title: Regent House Ballots application
+    service-owner: cb765
+    service-manager: ajc322
+    teams:
+      - jackson
+    engineers:
+      - rjw57
+
+  reporter:
+    category: intranet
+    title: Reporter
+    teams:
+      - jackson
+    engineers:
+      - mh2215
+
+  research-dashboard:
+    category: research
+    title: Research Dashboard
+    service-owner: dgb26
+    teams:
+      - johnson
+
+  rgea:
+    category: research
+    title: Research Grant Expenditure Application (RGEA)
+    service-owner: weer2
+    service-manager: weer2
+    tech-lead: ad2139
+    teams:
+      - johnson
+    engineers:
+      - snr21
+      - si202
+
+  ronin:
+    category: cloud
+    title: RONIN
+    service-owner:  amc203
+    service-manager: jpk28
+    teams:
+      - cloud
+    engineers:
+      - sdw37
+
+  roo-intranet:
+    category: research
+    title: ROO Intranet
+    tech-lead: meh37
+    teams:
+      - johnson
+
+  scribe:
+    category: other
+    title: SCRIBE
+    tech-lead: meh37
+    teams:
+      - jackson
+
+  self-service-gateway:
+    category: cloud
+    title: Self-Service Gateway
+    teams:
+      - cloud
+    engineers:
+      - im530
+
+  service-template:
+    category: other
+    title: service-template
+
+  sissp:
+    category: research
+    title: Staff Information System SharePoint portals (SIS/SP)
+    tech-lead: jl364
+    teams:
+      - johnson
+    engineers:
+      - jl364
+      - dj257
+
+  software-sales: # retired
+    category: generic
+    title: Software Sales
+
+  staff-information-system:
+    category: research
+    title: Staff Information System
+    service-manager: meh37
+    tech-lead: meh37
+    teams:
+      - johnson
+
+  statutes-and-ordinances:
+    category: intranet
+    title: Statutes and Ordinances
+    tech-lead: mh2215
+    teams:
+      - jackson
+    engineers:
+      - mh2215
+
+  streaming-media:
+    category: cloud
+    title: Streaming Media Service
+    service-owner: amc203
+    service-manager: si202
+    tech-lead: si202
+    teams:
+      - cloud
+
+  symphony:
+    category: other
+    title: Project Symphony
+    service-owner: amc203
+    service-manager: amc203
+    tech-lead: ad2139
+
+  talks-cam:
+    category: shared
+    title: talks.cam
+    service-manager: ad2139
+    teams:
+      - jackson
+
+  temporary-employment-service:
+    category: hr
+    title: Temporary Employment Service (TES)
+    service-owner: hmd26
+    service-manager: ajc322
+    tech-lead: az330
+    teams:
+      - holberton
+    engineers:
+      - prb34
+      - du228
+      - wgd23
+
+  time-allocation-survey:
+    category: hr
+    title: Time Allocation Survey
+    tech-lead: nb745
+    teams:
+      - jackson
+    engineers:
+      - nb745
+
+  tls-certificates: # retired
+    category: generic
+    title: TLS Certificates
+    service-owner: amc203
+    service-manager: rjg21
+
+  toast:
+    category: postgraduate
+    title: TOAST
+    tech-lead: meh37
+    teams:
+      - lovelace
+
+  university-human-resources-api:
+    category: iam
+    title: University Human Resources API
+    teams:
+      - wilson
+
+  university-student-api:
+    category: iam
+    title: University Student API
+    tech-lead: av603
+    teams:
+      - wilson
+
+  ups-service-definition:
+    category: finance
+    title: University Payment System
+    service-owner: sav25
+    service-manager: ajc322
+    teams:
+      - holberton
+    engineers:
+      - az330
+      - wgd23
+      - du228
+
+  utbs:
+    category: hr
+    title: University Training Booking System
+    service-owner: mg356
+    service-manager: mg356
+    tech-lead: prb34
+    teams:
+      - holberton
+    engineers:
+      - si202
+      - ad2139
+      - wgd23
+
+  web-recruitment-system:
+    category: recruitment
+    title: Web Recruitment System (WRS)
+    service-manager: ajc322
+    tech-lead: az330
+    teams:
+      - holberton
+    engineers:
+      - prb34
+      - du228
+      - wgd23

docker-compose.yaml

+version: "3.8"
+services:
+  guidebook:
+    build: .
+    volumes:
+      - type: bind
+        source: .
+        target: /workspace
+    ports:
+      - "8000:8000"
+    depends_on:
+      - plantuml
+  plantuml:
+    image: plantuml/plantuml-server:jetty
+    expose:
+      - 8080
+    volumes:
+      - ./compose/jetty-logging.properties:/var/lib/jetty/resources/jetty-logging.properties
+    environment:
+      - JAVA_OPTIONS=-Djava.util.logging.config.file=/var/lib/jetty/resources/jetty-logging.properties

docs/cards/diataxis/cards.yml

+- title: |
+    [Tutorials](site:tutorials/)
+  content: |
+    <img class="dtx" src="site:cards/diataxis/img/tutorials.jpg" alt="Tutorials">
+    <a href="https://diataxis.fr/tutorials/">
+      <span class="dtx-pill dtx-pill-need"><b>Learning</b></span>
+    </a>
+    <span class="dtx-pill">&#61;</span>
+    <span class="dtx-pill dtx-pill-skill dtx-pill-skill1"><b>Acquisition</b></span>
+    <span class="dtx-pill">&#43;</span>
+    <span class="dtx-pill dtx-pill-skill dtx-pill-skill2"><b>Action</b></span>
+
+    <h4 class="dtx">Learn to create & configure specific features & resources.</h4>
+    <h6 class="dtx">e.g. <i>"How do I add automated releasing to my Python library?"</i></h6>
+
+- title: |
+    [How-To's](site:howtos/)
+  content: |
+    <img class="dtx" src="site:cards/diataxis/img/howtos.jpg" alt="How-To's">
+    <a href="https://diataxis.fr/how-to-guides/">
+      <span class="dtx-pill dtx-pill-need"><b>Goals</b></span>
+    </a>
+    <span class="dtx-pill dtx-pill">&#61;</span>
+    <span class="dtx-pill dtx-pill-skill dtx-pill-skill1"><b>Action</b></span>
+    <span class="dtx-pill dtx-pill">&#43;</span>
+    <span class="dtx-pill dtx-pill-skill dtx-pill-skill2"><b>Application</b></span>
+
+    <h4 class="dtx">Guided examples of common workflows.</h4>
+    <h6 class="dtx">e.g. <i>"Walk me through making a new Python library?"</i></h6>
+
+- title: |
+    [Explanations](site:explanations/)
+  content: |
+    <img class="dtx" src="site:cards/diataxis/img/explanations.jpg" alt="Explanations">
+    <a href="https://diataxis.fr/explanation/">
+      <span class="dtx-pill dtx-pill-need"><b>Understanding</b></span>
+    </a>
+    <span class="dtx-pill">&#61;</span>
+    <span class="dtx-pill dtx-pill-skill dtx-pill-skill1"><b>Acquisition</b></span>
+    <span class="dtx-pill">&#43;</span>
+    <span class="dtx-pill dtx-pill-skill dtx-pill-skill2"><b>Cognition</b></span>
+
+    <h4 class="dtx">Our mechanisms & the motivations behind them.</h4>
+    <h6 class="dtx">e.g. <i>"Why do we use Poetry for packaging?"</i></h6>
+
+- title: |
+    [Reference](site:reference/)
+  content: |
+    <img class="dtx" src="site:cards/diataxis/img/reference.png" alt="Reference">
+    <a href="https://diataxis.fr/reference/">
+      <span class="dtx-pill dtx-pill-need"><b>Information</b></span>
+    </a>
+    <span class="dtx-pill">&#61;</span>
+    <span class="dtx-pill dtx-pill-skill dtx-pill-skill1"><b>Cognition</b></span>
+    <span class="dtx-pill">&#43;</span>
+    <span class="dtx-pill dtx-pill-skill dtx-pill-skill2"><b>Application</b></span>
+
+    <h4 class="dtx">Codex for specific information.</h4>
+    <h6 class="dtx">e.g. <i>"What Python library do we use to implement REST APIs in Django apps?"</i></h6>