Base Images
knot ships a curated catalog of base images that the template spec wizard presents as a picker. Each is an ordinary OCI image built from knot-base-images, preloaded with the knot entrypoint, an agent, and common dev tooling. You can also use any image (private or public) by typing its reference directly.
The catalog is versioned (manifest_version, format yyyymmddbb). Servers can keep it up to date automatically from https://getknot.dev/base-images.toml.
~/public_html.
All images are multi-arch (linux/amd64, linux/arm64). The versions above are image tags; older tags are kept in the catalog for compatibility, and the wizard marks the current default for new spaces as recommended.
Volumes
Each image declares the mount point(s) it expects to survive a space restart. When you pick an image in the spec wizard, a storage row is added for each — you then choose the backing kind (managed named volume, managed path, or bind).
| Image family | Persistent path | What lives there |
|---|---|---|
| Ubuntu / Ubuntu Desktop | /home |
User files, projects, shell config. |
| PHP / FrankenPHP / FrankenScriptling | /home |
As above; the web root is ~/public_html. |
| Go / Python / Node.js | /home |
Projects, GOPATH, virtualenvs, node_modules. |
| MariaDB | /var/lib/mysql |
The database data directory. |
| MySQL | /var/lib/mysql |
The database data directory. |
| PostgreSQL | /var/lib/postgresql/data |
The database data directory (PGDATA). |
| Valkey / Redis | /data |
RDB snapshots / AOF. |
| Mailpit | /data |
SQLite database of captured mail. |
| VictoriaLogs | /data |
Log storage directory. |
Web images (PHP, FrankenPHP, FrankenScriptling) also pre-fill a template port labelled Web on container port 80 (http) — that’s template routing metadata, not the raw network port in the spec.
Keeping the catalog up to date
The catalog compiled into the binary is a snapshot taken at release time. knot can fetch a published catalog from https://getknot.dev/base-images.toml (the default), or a URL of your choosing. Updates are gated by a master flag, off by default:
[server.base_image]
update_enabled = true # master gate; off by default
update_url = "https://your-mirror/base-images.toml" # optional; defaults to getknot.devWhen the gate is on, the server fetches once on startup and on demand via the admin command — there’s no periodic loop, so the catalog only changes on restart or an explicit refresh.
- Gate off → no remote fetch at all (not on startup, not via the admin command); the bundled or file catalog is used as-is.
- No manifest file configured → the server fetches from your
update_url(or the default URL). A fetched catalog overlays the bundled one only when itsmanifest_versionis newer. - Manifest file configured → the file is used and read from disk on every request, so editing it takes effect immediately. The server only fetches a remote when an explicit
update_urlis also set; otherwise the file is authoritative. When a remote is fetched, it overlays the file only when newer — bump the file’s version and it wins again straight away. - Every node fetches independently (full members and leaves alike), so the fleet converges on identical content with no cluster coordination.
To update a running cluster without restarting, the admin command fans the refresh out to every server:
knot admin refresh-base-images --server https://knot.example.com --token <admin-token>Each server must have update_enabled on; a server using a manifest file must also have update_url set, otherwise it reports a conflict and keeps its file. Pass --local-only to refresh just the connected server. See Template Spec Wizard → Base image updates for the full rules.
Source
All of these images are built from source in knot-base-images. Each image’s directory there has its own README covering bundled tools, entrypoint behaviour, and build instructions.