Skip to content

The Platform instance image

One container image carries the whole of Nerthus.Platform; the roles an instance runs are chosen when it starts, not when the image is built. This page is how a host gets the image and runs it.

registry.gitlab.com/margonem/nerthus/it/nerthus.platform:v<major>.<minor>.<patch>

A host pulls it by digest, from the pin a release wrote into versions.lock, never by tag. Only a release tag pushes an image; builds of merge requests and of main are run and measured and pushed nowhere (Cut a Platform release).

linux/amd64 only

The image has no arm64 half, and the pin is a single manifest rather than a list. A puller on arm64 gets no matching manifest, which is the honest answer. An arm64 host would need an arm64 build, which needs its own runner.

It stays in the private registry

The image carries the Polish spaCy model, which is GPL-3.0, so it is published only to the group's private registry; the language extra never ships in a public image. Pulling it needs a read-only registry credential on the host.

Run one

docker run --rm \
  -e NERTHUS_ROLES=read \
  -e NERTHUS_DATABASE_URL=postgresql://…  \
  -v nerthus-data:/var/lib/nerthus \
  registry.gitlab.com/margonem/nerthus/it/nerthus.platform@sha256:…
Variable What it decides
NERTHUS_ROLES The roles this process runs, comma-joined, or all. No default: an instance told nothing refuses to start.
NERTHUS_CONFIG The nerthus.toml the host mounts. Empty means there is none and NERTHUS_* is the whole configuration.
NERTHUS_DATA_DIR The instance's directory: its cluster, the unpacked Postgres, everything the site owns. /var/lib/nerthus; give it a volume.
NERTHUS_DATABASE_URL A Postgres the instance does not run. Unset, it runs the bundled one.

Every other key is in Configure a Platform instance. Secrets reach a container as files mounted under /run/secrets, never as environment variables.

The entrypoint is nerthus, so docker run <image> db status is the same command an operator runs on a laptop; the default command is serve.

What it does at boot, and what it does not

  • It runs the bundled Postgres as an unprivileged user, because postgres refuses to run as root: nerthus db init && nerthus db start works inside the container.
  • It clones nothing. Corpora arrive through nerthus corpus add and the fetch role, which converges them on a tick; nothing writes to a volume at boot.
  • It renders no configuration file from the environment: NERTHUS_CONFIG names a file the host mounts, and NERTHUS_* overrides it.