Zero to Hero (Interactive Setup)

The interactive wizard is the shortest path from a fresh install to a working norsk-ctl configuration. Run norsk-ctl init with no flags in a terminal and a form-style UI walks you through every field — network mode, TLS cert source, public host, proxy user. No manual YAML.

Licenses are not part of init: the license is supplied later, when a product is registered (norsk-ctl product add --license-file <path> or --marketplace-provider <aws|gcp>), and is stored on the product registration.

Note

If you prefer the flag-driven CLI form, see Zero to Hero (CLI). The interactive wizard and the flag form write the same config.yaml.

Starting the wizard

Run the command with no arguments:

$ norsk-ctl init

You’ll see a bordered form. The ▶ marker shows the active field; Tab / Shift-Tab cycle through.

╭───────────────────────────────────────────────────────────────────────╮
│ norsk-ctl setup                                                       │
│ Tab to move between fields · Enter to submit field · Esc to cancel    │
│                                                                       │
│ ▶ Network mode                                                        │
│     docker — bridge network + reverse proxy (typical)                 │
│                                                                       │
│   TLS                                                                 │
│     mkcert — local development only                                   │
│                                                                       │
│   Public host (optional)                                              │
│                                                                       │
│   Working directory (optional)                                        │
│                                                                       │
│   Add proxy user (optional)                                           │
│                                                                       │
│   [ Submit ]  [ Cancel ]                                              │
╰───────────────────────────────────────────────────────────────────────╯

Path fields — with path completion

In path fields (working directory, user-supplied cert + key), start typing and the wizard fuzzy-matches children of the current directory, ghosting the likely completion inline. Fish-style — there’s no “TAB to accept”, just keep typing or press Enter when the suggestion looks right:

▶ Working directory root (optional)
  /Users/alice/norsk-r_[untime]

The ghosted portion (in brackets above) shows as dimmed text in your terminal. Press Enter and the wizard validates the path, then advances to the next field. ~/ is expanded before validation.

Network mode

On Linux, pick docker (bridge network behind the reverse proxy — the typical choice) or hybrid (same as docker, but the media container runs on the host network for kernel-direct, low-latency ingest). Studio sits behind the proxy either way.

On macOS, docker is the only option — hybrid relies on Linux host networking which Docker Desktop doesn’t provide. The wizard shows this explicitly, struck through in yellow for the unavailable option.

▶ Network mode
  ● docker — bridge network + reverse proxy (typical)
  ✗ hybrid — media on host network for low-latency ingest  (unavailable on macOS)

TLS

Four cert sources — arrow keys to change. There is no insecure / plain-HTTP option — that mode was removed (#280). Every install gets TLS.

▶ TLS
  mkcert — local development only (auto-install, may prompt for sudo) — https://github.com/FiloSottile/mkcert
  self-signed — remote server with no domain (openssl; browser shows a one-time warning)
  certbot — Let's Encrypt (needs public DNS)
  user-supplied — bring your own cert + key

Decision summary:

Have a DNS name?	Pick
Yes, public	certbot — auto-issued and auto-renewed Let’s Encrypt
Yes, internal CA	user-supplied — point at your cert + key paths
No, this is your laptop	mkcert — installs a local CA so dev browsers trust the cert
No, this is a remote VM	self-signed — covers the configured public host / IP

certbot is greyed out on macOS (no good runtime there). user-supplied reveals two extra fields (TLS certificate, TLS private key) that must point at existing PEM files. mkcert and self-signed both kick off an automated pipeline after you submit — see mkcert: the fully automated path below.

Public host

The hostname or IP your clients will type into the browser. It’s baked into the TLS cert SAN, and it’s the prefix the proxy advertises for per-instance URLs.

▶ Public host (optional)
  norsk.example.com

Leave blank for a localhost-only install (useful on a laptop with no remote clients). For server installs, set it to the DNS name (certbot / user) or the public IP (self-signed). The installer’s --ip auto path does this for you on a public cloud VM.

mkcert: the fully automated path

If you pick mkcert, you don’t enter any cert paths. After you submit, the wizard exits Ink and runs the mkcert pipeline in the plain terminal:

Setting up local-trust TLS with mkcert
  https://github.com/FiloSottile/mkcert
  mkcert not found — downloading…
  100%
  downloaded: /Users/alice/.norsk-ctl/bin/mkcert

  About to install the mkcert root CA into your system trust store.
  This requires sudo and will prompt for your password.
  Press Enter to continue (Ctrl-C to abort)…

Password: ********

  running mkcert -install…
  The local CA is already installed in the system trust store!
  generating cert for: localhost, 127.0.0.1, ::1
  wrote /Users/alice/.norsk-ctl/certs/cert.pem

On repeat runs the wizard notices the CA is already in your trust store and skips the sudo prompt entirely.

The generated cert + key are written to ~/.norsk-ctl/certs/, and the wizard patches certPath / keyPath / certSource: mkcert onto the config before writing config.yaml.

Caution

After mkcert -install finishes, fully quit and restart your browser (cmd-Q, not just close the window). macOS browsers cache the trust decision per-session and will keep showing “Not Secure” until you restart.

Firefox uses its own cert store (not the macOS Keychain). If you’re on Firefox, install NSS tools first so mkcert -install can reach Firefox too: brew install nss, then re-run mkcert -install.

Self-signed: covering your remote IP

Picking self-signed runs openssl to mint a cert whose SAN covers the publicHost value (DNS name) or detected IP. There’s no CA install — every browser shows a one-time “not trusted” warning that you click past.

This is the default cert source for install.sh --server when no --cert-source is passed and no --domain is provided.

Proxy user (optional)

Type a username and press Enter — the wizard reveals a password field:

▶ Add proxy user (optional)
  admin

  Proxy password
  ********
  ≥8 chars, includes a digit

Skip it by leaving the username blank and tabbing onward. Existing users (from a previous run) are shown as a hint and not re-prompted — the wizard only ever adds users from here.

Existing config — overwrite confirmation

If a config.yaml already exists, the wizard shows a yellow warning pre-screen before the form appears:

╭───────────────────────────────────────────────────────────────────────╮
│ norsk-ctl setup                                                       │
│                                                                       │
│ ⚠  Existing config detected — continuing will overwrite it and wipe   │
│    the instance database.                                             │
│                                                                       │
│ Current config                                                        │
│ Network mode:  docker                                                 │
│ Cert source:   mkcert                                                 │
│ Proxy users:   admin                                                  │
│                                                                       │
│ Proceed? y/N                                                          │
╰───────────────────────────────────────────────────────────────────────╯

Type y to continue into the form (seeded with the current values as defaults) or n to exit. Either way the existing database is preserved until you actually submit.

Submit — what gets written

After Submit, the wizard prints the equivalent flag-driven command:

Config written to /Users/alice/.norsk-ctl/config.yaml
Proxy user(s) created: admin
Equivalent command: norsk-ctl init --network-mode docker --cert-source mkcert --proxy-user admin --proxy-password '<redacted>'

Copy that line if you’re setting up another machine — it’s script-safe (password is redacted as a literal placeholder; substitute your own).

After init

The daemon auto-starts on the next norsk-ctl command that needs it. Register a product if you haven’t yet (Quickstart step 2), then launch one of its templates:

$ norsk-ctl instance launch-template my-studio --template studio-examples --param INSTANCE_NAME=my-studio

Or visit the web UI at https://localhost/ (or whatever publicHost you set) — see the web UI walkthrough for the full guide.

Keyboard reference

Key	Action
Tab / Shift-Tab	Move between fields
Enter	Submit the current field (validates + advances)
↑ / ↓	Change selection in a Select field
Esc	Cancel the wizard (no config written)
Ctrl-C	Abort at any point