self-hosted-cookbook: docker-compose recipes that assume you will edit them

The gap this fills: image authors who do not ship a working compose file

The README states the motivation directly: not all image authors document their images the way linuxserver.io does, where you copy the compose file, run docker-compose up -d, and it works. The author's claim is that some images take a lot of time to get running, and this repository exists to hold recipes you can copy, paste and run. That is a narrower goal than a self-hosting catalogue. It is a file collection with opinions embedded in the files.

The audience is someone who already knows docker-compose and wants the missing environment variables, volume paths, ports and dependency ordering for a specific app. It is not aimed at people who have never run a container. The README links to docker/get-started.md and docker/troubleshooting.md as general entry points, which suggests the author expects readers to arrive with the basics already in place.

How the cookbook is laid out and what the link icon means

The README is the index. Apps are grouped by function: Ad Blockers & local DNS, Analytics, Antivirus, Backup, Blogging & CMS, Bookmarks & Read Later, Cloud & File Sharing, Contacts and calendars, Dashboard, Database, Docker Managers, Document Managers, Download Managers and E-mail. Each entry is either a relative path into the repository, such as apps/ad-blockers/adguard.md or apps/cloud/nextcloud.md, or an external URL.

The external URLs are marked with a link icon, and the README explains the convention: not all apps have been tested and described, and those are marked with the icon. That single sentence is the most important thing to understand about the repository. A path like apps/analytics/matomo.md points at a recipe the author wrote. A URL like the Swetrix self-hosting docs or the MalwareMultiScan GitHub page points at someone else's instructions, included because the app belongs in the category, not because the recipe was verified here. The two kinds of entry sit in the same list, so you have to read the marker.

The category structure also carries opinions. Under Bookmarks & Read Later, Nunux Keeper is described as similar to wallabag but more complicated and without mobile apps. Under Cookbook, the NextCloud Cookbook app is described as quite good but painful for manually editing longer recipes, because ingredients and steps must be added one at a time. Those notes are the author's own experience, and they are the kind of thing a plain link list cannot give you.

What you must edit before a recipe will run

The README lists the substitutions that cannot be shipped pre-filled for security reasons. example.com must be replaced with your own domain. Placeholders such as username and password must be replaced with your own. Keys such as APP_KEY or SECRET must be regenerated, and the README gives the command: openssl rand -base64 32.

That is the whole onboarding contract. There is no installer, no .env template generator, no variable validation. You open the recipe, find the placeholders, and replace them. If you skip the key regeneration step and run a recipe with the sample value, you have deployed an app with a publicly known secret, which for a CMS or an analytics tool is a direct exposure rather than a cosmetic problem.

The general documentation lives in two files, docker/get-started.md and docker/troubleshooting.md. The README does not describe their contents, so how much they cover beyond the placeholder rules cannot be confirmed from the material available.

Verification coverage is uneven and the README admits it

The repository mixes tested recipes with untested pointers, and the marker system only distinguishes them by an icon. There is no separate changelog per recipe, no date on individual entries, and no release history: the material shows no releases retrieved. The last push date is 2026-08-18, so the repository is active, but activity at the repository level says nothing about whether the Ghost recipe was checked against the current Ghost image.

This matters because self-hosted images move. A compose file that pinned a working combination of image tags a year ago may still start and still be wrong, for example if an upstream image changed its default data directory or added a required environment variable. The cookbook has no mechanism visible in the material for recording which image tag a recipe was validated against. Treat every recipe as a starting point that you will finish, not as a tested artefact. The author's own framing supports this: the recipes are described as ready-to-run, but the same README warns that not all apps have been tested.

How it differs from awesome-selfhosted and from a deployment tool

awesome-selfhosted, linked in the README under Other self-hosted sources, is a catalogue. It tells you that a project exists and links to its homepage or repository. It does not give you a compose file, and it does not tell you that the NextCloud Cookbook app is annoying to edit by hand. The cookbook inverts that: fewer entries, but each file-backed entry is supposed to contain the configuration.

The other comparison is with a deployment tool rather than a list. Homelab OS, also linked from the README, is described by its own documentation as offering available software, which implies an installer or orchestration layer that manages the deployment for you. The cookbook does not manage anything. It is markdown and compose files. If you want something that tracks state, handles upgrades and rolls back, this is the wrong shape of project, and no amount of reading the recipes will change that. The trade-off is deliberate: files you can read in full versus a system that hides the details.

Maintenance, licence and what GPL-3.0 means for a recipe collection

The repository is GPL-3.0. For a collection of compose files and markdown notes, the practical question is what you do with the recipes. Copying a recipe into your own private infrastructure repository is normal use. If you redistribute the cookbook or a modified version of it, the licence terms apply to that redistribution. Nothing in the material indicates a per-recipe licence or a dual-licence arrangement, so the repository licence is the one to read. This is not legal advice; read the licence text if you plan to publish a derived collection.

Upgrade cost is the interesting part. Because the recipes are plain files, there is nothing to upgrade in the cookbook itself. You pull the repository, or you copy the file once and never look again. The cost sits on the other side: when an upstream image changes, the recipe does not update itself, and you will not be notified. Tracking the repository means re-reading recipes you already deployed and diffing them against your own edited copies, which is manual work with no tooling provided here.

Who should adopt it and who should not

Adopt it if you run docker-compose on a home server or a small VPS and you want a head start on the fiddly parts of a specific app: the environment variables, the volume mounts, the port mappings. The categories are broad enough that you will likely find the app you are deploying, and the file-backed entries give you something concrete to edit rather than a documentation page to interpret.

Do not adopt it as your source of truth. It has no releases, no versioning per recipe and no verification dates, so it cannot tell you whether a recipe still matches the current image. Do not use it if you need orchestration, secrets management or upgrade automation, because it provides none of those and is not trying to. And do not copy a recipe without reading it end to end: the placeholders for domain, credentials and keys are intentional, and a recipe run unedited is a misconfigured deployment rather than a shortcut. If you want a catalogue to browse rather than files to run, awesome-selfhosted is the better fit for that specific job.

Editorial conclusion

Adopt this cookbook if you already run docker-compose and want a starting file per app rather than a catalogue of links; the recipes that exist as files in apps/ are the ones to read first. Skip it if you want a maintained, versioned deployment system, because there are no releases and the repository is a set of markdown files. Before running any recipe, open the file and replace example.com, the username and password placeholders, and every key such as APP_KEY or SECRET with output from openssl rand -base64 32, and treat any entry marked with the link icon as a pointer to upstream documentation rather than a tested recipe.

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. tborychowski/self-hosted-cookbook on GitHub