Runbooks

The Manifesto

• We are tired of haphazardly hunting through messy threads of GitHub issues and StackOverflow when we hit a problem

• We don't want a one-off fix, we want to deepen our understanding of the problem space

• We want to give people a resource where they can benefit from our experience in a scalable way

What

A collection of step by step guides for fixing common tech problems.

The content is published here

Requirements

Submodules

Hugo uses submodule for themes so when you are cloning this repository you should pass the --recursive flag:

git clone --recursive git@github.com:ContainerSolutions/runbooks.git

Running hugo locally

Docker

If you have docker compose installed you can simply call and you should see the blog at http://localhost:1313/runbooks/

$ docker-compose up

Alternatively, without docker compose:

$ docker build -t runbooks-hugo .
...
$ docker run -v $PWD:/src -p 1313:1313 -d runbooks-hugo

Local Install (runs really fast)

First install hugo then from this repository run:

hugo serve -D

Github pages deploy

The deploy to Github Pages is controlled by this action. The reference to this is found in .github/workflows/main.yml.

To update the key used

1. create an SSH key and put the private key into a secret called GIT_DEPLOY_KEY here.
2. add the public key as a deploy key with write access here.

More granular details are available on the action page.

Debugging

The Hugo docs can occasionally be a bit vague about what methods are available or what they return. There also seems to be quite a bit of push-back to adding general debugging tools. One user has created a theme that includes a partial and a shortcode to work around this limitation.

If you are working from inside a partial or layout file you can include the following partial and pass the property that you wish to inspect. I'm using .File in the example below.

{{ partial "debugprint.html" .File }}

This will show you various properties available via .File.

If working within a content file things are a lot more limited but you can pass the following variants to get appropriate output:

{{< debug "params" >}}
{{< debug "site" >}}
{{< debug param="title" >}}

but generally you will get more use when invoking the debugprint partial directly.

Adding content

Run:

hugo new posts/path/article-name.md

Then git add, commit, raise PR as normal.

License

See LICENSE