Registry configuration

Nosdesk installs plugins from a signed registry. The official image is wired to the registry at nosdesk.com and verifies everything against a public key baked in at build time. Most operators never touch any of this. The reasons to change it are running offline, or hosting your own registry for a fork.

How the registry works

On startup, and again every 24 hours, Nosdesk fetches four files from the registry base URL:

{base}/publishers.json      {base}/publishers.json.sig
{base}/index.json           {base}/index.json.sig

publishers.json lists the trusted publishers and their tiers. index.json lists the available plugins and versions. Each .sig is an Ed25519 signature over the matching JSON document, made with the registry root key. Nosdesk verifies both against the root public key compiled into the binary, and rejects any document whose version is lower than the highest it has already accepted. That last rule is anti-rollback: a valid but stale snapshot can’t be replayed to walk an instance back to an older, possibly compromised catalogue.

Sync is best-effort. A fetch that fails logs a warning and leaves the cached registry in place. It never blocks startup or pulls already-installed plugins offline.

NOSDESK_REGISTRY_URL

This sets where to fetch from. It defaults to https://nosdesk.com/registry. There are two reasons to set it:

• Run offline. Set it to an empty string and Nosdesk skips registry sync entirely. Plugins still install from the CLI and the filesystem (see Plugins without a registry); you just don’t get the hosted catalogue or publisher updates.
• Point at your own registry. Set it to your base URL. See Running your own registry.

The baked-in root key

The registry’s trust root is an Ed25519 public key compiled into the binary, not a runtime setting. The official Docker image carries the Nosdesk root key, and its public half is published at https://nosdesk.com/registry/root.pub so anyone rebuilding an official image can confirm they baked in the right one.

It has to be a build-time value. The root key is what every registry signature chains back to, so making it swappable at runtime would let anyone who can set an environment variable redirect trust. You only deal with it when you build your own image. A binary built with no root key can’t verify a registry signature at all, so official and verified plugins fail closed and only CLI-installed and filesystem-provisioned plugins work.

Running your own registry

For a fork that wants its own trust root and catalogue:

1. Generate a root keypair. Any Ed25519 keypair works. Keep the private key offline and treat it as long-lived: rotating it means rebuilding every instance, since the public half is compiled in.

2. Build a custom image with your public key. Pass it as a build arg, base64 of the raw 32-byte key (the same format as root.pub), so it’s baked in:

   docker build --build-arg NOSDESK_ROOT_PUBKEY='<your-base64-pubkey>' \
     -f backend/Dockerfile -t your-org/nosdesk .

3. Host the four files at your registry base URL. Sign each JSON document with your root private key over the bytes nosdesk-registry-v1: followed by the literal file contents, base64 the resulting 64-byte signature, and serve it as the matching .sig. Give each document a version integer and only ever increase it.

4. Point your instances at it with NOSDESK_REGISTRY_URL=https://registry.your-org.example.

Nosdesk doesn’t ship a tool that assembles and signs these files. Any Ed25519 signing setup produces them, whether that’s a short script, openssl, or a step in your CI, as long as the signing input and the version rule above hold.

Plugins without a registry

The registry is one way plugins arrive, not the only one. Both of these work with sync disabled or no registry configured:

• CLI install. nosdesk-cli plugin install <zip> adds a signed plugin directly. A plugin you signed with your own key lands at the local trust tier.
• Filesystem. Drop signed *.zip files into the plugins directory (NOSDESK_PLUGINS_DIR, default /app/plugins; the Compose file mounts ./plugins there). They’re provisioned on startup.

Both verify the signature against the trust chain like any other install. The registry handles distribution and publisher identity; it isn’t what checks the signature.

What’s allowed to run

A registry can advertise plugins at the official, verified, and community tiers, and CLI or filesystem installs come in as local. NOSDESK_ALLOWED_PLUGIN_TIERS decides which tiers actually load, and it defaults to official,local. Verified and community plugins run third-party code in-process, so they stay off until you opt in. Syncing a registry that lists a community plugin doesn’t mean it runs; the allowed-tiers gate has the final say.