Geek Cookbook: self-hosting recipes built as a heavily customised MkDocs site

Four platform pieces, reused by every recipe

The recipes are written as progressive guides for running applications on Docker Swarm or Kubernetes, and the examples named are AutoPirate, a bundle described as Radarr, Sonarr, NZBGet and friends, along with Plex and NextCloud. What makes them more than per-application documentation is a shared platform layer that appears repeatedly. Automatic secure access to every service is handled by a reverse proxy with Let's Encrypt certificates, so no recipe has to solve TLS. An authentication layer sits in front of services that have none of their own, which is described in terms of protecting unsecured or vulnerable services, and it is implemented as a forward-auth middleware in the proxy. Backups of configuration and data are automated rather than described, with ElkarBackup named for the job. Monitoring, graphing and alerting come from a Prometheus and Grafana stack called SwarmProm. Learn one of those four and every later recipe is shorter, which is the whole design argument of the project.

The audience is defined by what you already know

There is a section that says who this is for, and it is written as a filter rather than a welcome. You are expected to be comfortable with virtual machines, Docker containers, Let's Encrypt certificates, databases and command line interfaces, and to have already self-hosted something mainstream such as Plex, NextCloud, WordPress or Ghost. Then a section asks why you would read further and answers with three motives. The first is upskilling, framed around container orchestration, Prometheus, Grafana and Kubernetes. The second is play, wanting a safe sandbox to try new tools and keep the ones that work. The third is reliability, and it is illustrated with a small piece of prose that describes restarting Plex over ssh on a basement server as no longer acceptable once someone else depends on you watching something with them. That is a better definition of production than most documentation gives you, and it is worth reading before the recipes.

The README is a landing page, and it is assembled from a snippet

The readme is not documentation, it is the front door, and it shows it. The opening is a centred block of badges and a greeting, followed by a table of contents whose links point at sections that explain what the project is, who it is for, why to read it, and how to support the author. The last section does not exist in the readme at all: it is a snippet include directive pointing at a file called work-with-me.md, which the site build pulls in, so part of what you read on GitHub is assembled at documentation build time. Roughly half the file is about funding. Sponsorship through GitHub Sponsors or Patreon is described with tiers whose benefits are listed as warm fuzzies, access to a pre-mix repository, an anonymous plug you can pull at any time, and more loot at higher tiers, followed by a line about the money being spent on wine, cheese and cryptocurrency. Community links cover a Discord server, a Discourse forum, Twitch, a Mastodon account and a personal site, and the Discord address is served over plain http.

A vendored theme, three configurations, and a paid tier config

The build tree is where this project stops being a folder of Markdown. There is a directory named for the theme itself at the root, which means the Material for MkDocs theme is vendored into the repository rather than installed as a dependency, and it is accompanied by overrides, layouts and extra_sass directories for customising it. On top of that sit three separate MkDocs configuration files: the ordinary site configuration, a second one for the paid Insiders edition of the theme, and a third for PDF output. Two container files exist, one for the site and one for the PDF build, and there are directories named for the PDF template and for an event hook that runs during that build. This is what a long-lived documentation project accumulates: not recipes, but a publishing toolchain. The practical consequence is that the site is not reproducible with a plain pip install of the requirements file, because the theme and the templates are part of the repository.

The requirements file comments out a pin and installs the package anyway

The requirements file opens with a line that is not a requirement at all, because it is commented out with two hash characters, and it carries a version constraint for a link-checking plugin. Further down the same plugin appears again as a bare package name with no constraint. So there are two different statements about the same dependency, one disabled and one active, and the container takes the unconstrained path because it installs the package by name rather than from this file. The container also pins BeautifulSoup to a version from 2020 while leaving most of the rest of its pip install unpinned, which is a different policy again from the requirements file, where direct dependencies carry lower bounds. Two further lines in that file are the kind of thing that only appears when someone appended to it over years: a section comment for direct dependencies, and another for the author's own plugins. None of this breaks the site. It does mean local and container builds are not guaranteed to install the same versions of the link checker.

The base image is a build argument, and the browser support is commented out

The site container opens with a build argument whose default is somebody else's image, followed by a from instruction using that argument, so the base can be swapped at build time without editing the file. On top of it comes a long apk add line pulling in pip, imaging and font packages, cairo for SVG rendering and the build tooling needed to compile extensions, then a pip install that pins one package and leaves the rest floating. Two comments are worth reading. The first is a fully written out block for adding headless Chrome and a font family, every line commented out, and one of the commented lines ends with a continuation character that would break the build if anyone uncommented it carelessly. The second is a single git config line marking the docs directory as safe, which exists because the container runs git against a mounted directory owned by a different user. Set against that, there is a separate container for the PDF build and a runtime file that pins a Python version the way a hosting platform would.

PDF output rides on a book file, a template hook and a Heroku style pin

The book build is the most involved part of the repository. It has its own container file, its own MkDocs configuration, a directory for the PDF template and a directory for an event hook that runs while the PDF is produced, and a text file named book.txt at the root, which is the traditional name for the single master document that LaTeX toolchains concatenate. The PDF plugin, the hook, the template and that master file together are four moving parts for one output format, and the hook exists so the build can behave differently when it is producing a book than when it is producing a website. Alongside them sit a redirects file for Netlify, a Gitpod configuration so the site can be opened in a cloud development environment, an exclude file telling git what not to track, a Markdown lint configuration, and a directory of example scripts. The repository also carries its licence as a Markdown file rather than the plain text name most tools expect.

Editorial conclusion

The Geek Cookbook fits someone who has already run a container or two and wants the boring platform layer assembled once, rather than assembling it again per service. It does not fit a beginner, and it says so itself, which is rarer and more useful than a tutorial that pretends otherwise. Before working through it, check four things. Which orchestrator you want, since the guides exist for both Docker Swarm and Kubernetes and are not interchangeable. Whether the defaults suit you, since automatic certificate issuance, an authentication proxy and monitoring are opinions baked into every recipe. What the surrounding build actually contains, because a documentation repository with a vendored theme, a disabled version pin and an overridable base image is a supply chain surface as well as a website. And whether you are reading the site or the repository, because the two answer different questions and the site is where the recipes live.

Frequently asked questions

Official sources

1. geek-cookbook/geek-cookbook on GitHub
2. Issues
3. License: MIT
4. Project website
5. README