Templates (yoink add)

What a yoink add template is, how it handles secrets and hardening, and how template versions resolve.

Read as MarkdownEdit on GitHub

yoink add <name> is the “poor man’s helm” for accessories and full apps. It fetches a template from GitHub and asks for a few variables. The result is a sealed secret and a working service fragment, with an optional deploy. The same code path serves the bundled templates and third-party repos.

Anatomy of a template

A template is a directory with a manifest and one or more template files. The manifest (template.yaml) declares variables and outputs. yoink renders the files through minijinja.

Each rendered file must parse as a yoink ConfigFragment, the same shape that you write by hand in yoink.yaml. yoink parses the file before it writes it. Thus a bad template fails closed and does not write a broken config.

A complete clickhouse example is in Write a template for yoink add. The fields are in the Template manifest reference.

Secrets stay local

For each secrets: entry of a manifest, yoink generates a random base32 string locally. yoink seals the string into secrets.age before the value leaves the process. The bytes are random and are not derived from anything.

yoink renders the secret name through minijinja, so each instance can have its own secrets. Two postgres instances do not collide on a shared POSTGRES_PASSWORD. The convention is {{ service_name | upper }}_<KIND>, so that the reference on the env-var side reads naturally.

If yoink.yaml has no secrets: config, yoink add offers to bootstrap age. A template does not have to handle that case.

Hardening overrides

The container defaults of yoink are deliberately strict:

options:
  user: "65534:65534"          # nobody
  cap_drop: [ALL]
  read_only: true              # rootfs only; volumes are still writable
  security_opt: ["no-new-privileges:true"]
  pids_limit: 1024

For most templates these defaults are correct. Some popular images need overrides, because their entrypoint starts as root, writes to the rootfs, or runs chown on a fresh volume. The pattern is “fail closed, then add back what is strictly necessary”.

Most bundled templates have a few lines of overrides for these reasons. They are models for a similar template:

A permission failure on the first deploy does not show in the manifest validator or in the rendered-YAML linter. It occurs only when the container starts. For that reason a template needs a test on a real host. The symptoms and their overrides are in Correct a permission failure on the first deploy.

Versioning and pinning

yoink fetches a template from a GitHub commit. As a result, each iteration on a template means a commit and a push.

A ref can be a branch, a tag, or a SHA. yoink resolves a branch or a tag to a SHA one time and caches the mapping. --refresh makes yoink resolve the ref again. A SHA ref is content-addressed, so yoink never resolves it again. The table is in Template refs.

A published template has two common pins. main moves fast and accepts upstream changes. A specific tag gives stability.

yoink_min_version: in the manifest protects a template that needs a newer yoink feature. An older yoink then stops with an “upgrade yoink or pin the template to an older version” message. Without it, the older binary can silently render a wrong config.

Publishing patterns

Any GitHub repo works, because yoink fetches a template as a gzipped tarball from https://codeload.github.com/.... A template can live in its own repo, in a templates monorepo, or in a directory of an existing project. yoink caps the size of the download. Thus a template in a large monorepo works, but a template in a multi-GB repo does not.

The layouts and the caps are in Publish a template.

The bundled set

Six templates are bundled: postgres, redis, meilisearch, rustfs, restic-backups, and openclaw. They live in the yoink repo at /templates/. yoink add postgres, with no gh: prefix, resolves to them.

PRs that add new bundled templates are welcome. The bar: the template is common enough that it saves many people the work to find the hardening overrides. The acceptance criteria are in Submit a template to the bundled set.

See also

Type a flag, a config field, or a task.