Backup & Upgrade

norsk-ctl keeps its state in three places. To restore a machine to a working state you need all three.

What to back up

Path	What it holds	Recoverable without?
`~/.norsk-ctl/config.yaml`	Daemon settings — network mode, image tags, TLS, public host	Yes — re-run `norsk-ctl init`
`~/.norsk-ctl/norsk-ctl.db`	SQLite: instance records (including their launch configs / sidecars / workflow paths)	No — instances and their settings have to be rebuilt by hand
`~/.norsk-ctl/certs/`	Generated TLS material (mkcert / self-signed). User-supplied certs live wherever `certPath` points	mkcert / self-signed regenerate; user / certbot certs live outside this tree
`<workingDirectory>/`	Your plugins, workflow YAML save-files, dashboards	No — this is your content
Norsk license file	Whatever path each product registration points at (set via `product add --license-file`)	Get a fresh copy from Norsk Video

The complete backup set is ~/.norsk-ctl/ plus your working directory plus your license. Tar it, snapshot it, sync it — whatever fits your ops setup.

Restoring onto a fresh machine

Install norsk-ctl (see Server install — overview). Don’t run init yet.
Restore ~/.norsk-ctl/ and the working directory from your backup, preserving permissions.
If the working directory path changed, edit ~/.norsk-ctl/config.yaml accordingly. If a product’s license path moved, re-register the product (norsk-ctl product add --license-file <new path>). Otherwise the daemon will start with the same state as the old machine.
Start the daemon (sudo systemctl start norsk-ctl on --server installs).
Re-launch each instance from norsk-ctl instance list — their launch configs are persisted in norsk-ctl.db, so a norsk-ctl instance restart <id> (or relaunch) is enough.

If you’re moving to a different publicHost, re-issue the TLS cert against the new name:

sudo norsk-ctl init --force --public-host new.example.com --cert-source self-signed

Upgrading the norsk-ctl binary

The binary checks for newer versions via /api/upgrade/check (against an S3 channel pointer). When a newer version is available, the web UI nudges. Disable the check with NORSK_CTL_UPGRADE_CHECK=0 in the environment, or upgradeCheckEnabled: false in config.yaml.

Upgrade path, conservatively:

Back up ~/.norsk-ctl/ first. Always.
Stop instances you can afford to interrupt. The new daemon handles a running set fine on most upgrades, but a clean shutdown sidesteps any subtle migration interaction.
Replace the binary. For --server installs, the simplest path is to re-run the installer with --server — it detects an existing install and updates the binary in place. For --local installs, the binary lives at ~/.local/bin/norsk-ctl.
Restart the daemon. sudo systemctl restart norsk-ctl (or norsk-ctl restart).
Migrations run automatically. The daemon runs forward-only schema migrations against norsk-ctl.db on first start of a new version. Migrations are wrapped in SQLite transactions; a failed migration aborts startup with a clear error and leaves the DB at the previous version.

Upgrading Studio and Media images

Studio/Media versions come from the product template’s compose pins — there is no daemon-global default tag to bump. To run a different version on an instance:

norsk-ctl instance relaunch <id> --studio-tag <new> --media-tag <new>

relaunch (vs restart) tears down and recreates the containers with the new tags. The launch config in norsk-ctl.db is updated so subsequent restarts use the new tags too.

Changing version always means a new product template — there is no per-launch image override. Existing instances keep the product template pin they were launched with.

Rollback

If the new binary misbehaves:

Stop the daemon.
Replace the binary with the previous version (keep a copy before upgrading — there’s no built-in version archive).
Restore norsk-ctl.db from backup. If new schema migrations ran, the old binary cannot read the migrated DB.
Restart.

This is why step 1 of any upgrade is “back up ~/.norsk-ctl/”.