Cloud deployment

Two paths to running norsk-ctl in the cloud: a marketplace image with everything pre-installed, or a manual install on any VM that can run Docker.

GCP marketplace

A pre-built Ubuntu image that ships norsk-ctl + Docker + systemd integration. Launch it from the GCP marketplace and the first boot auto-configures everything based on instance metadata.

Instance metadata

Set these on the VM at creation time (GCP console → Management → Metadata, or via gcloud compute instances add-metadata):

Key	Required	Description
norsk-studio-admin-password	yes	Password for the initial proxy user (norsk-studio-admin). Setting this triggers first-boot init
deploy_domain_name	optional	Domain name for the VM. Enables Let’s Encrypt via certbot for HTTPS
deploy_certbot_email	optional	Contact email for Let’s Encrypt. Required if deploy_domain_name is set

Without a domain, the first boot generates a self-signed certificate and you get HTTPS on the VM’s public IP (with a browser warning).

First boot flow

The startup script (deployment/google/files/gcp-startup.sh) on the image:

1. Reads the metadata keys above.
2. If config.yaml doesn’t exist yet, runs norsk-ctl init --network-mode docker with the metadata values, plus --cert-path/--key-path from either Let’s Encrypt or a generated self-signed cert.
3. On every boot, refreshes externalUrl in config from current instance metadata (to catch IP changes).
4. Execs norsk-ctl serve as a systemd unit.

Within a couple of minutes of VM boot you should be able to reach the web UI at https://<vm-ip-or-domain>/ and sign in as norsk-studio-admin.

Image build pipeline

Marketplace images are built from deployment/google/ (see 01-build.sh through 04-publish.sh). The source for the installed layer is deployment/google/files/install.sh.

AWS marketplace

licenseMode: marketplace accepts marketplaceProvider: aws in config.yaml, but a built AWS image / deployment pipeline is not shipping yet.

Coming soon

AWS marketplace image is planned alongside GCP. Until then, use the manual install path below on an EC2 VM.

Manual install (any cloud VM)

Works on any Linux VM with Docker:

# On the VM
curl -fsSL https://norsk.video/install-ctl.sh | bash

# Initialise — pick a network mode, point at your license
norsk-ctl init \
  --network-mode docker \
  --license-file /path/to/license.json \
  --proxy-user admin \
  --proxy-password '...' \
  --cert-path /etc/norsk-ctl/tls/cert.pem \
  --key-path  /etc/norsk-ctl/tls/key.pem

# Start the daemon (typically via systemd — see the GCP unit file as a template)
norsk-ctl serve

See Network Modes to pick the right --network-mode for your topology, and Configuration for the full list of init flags.

Security

• Firewall the daemon port. The daemon API listens on 8333. Only the proxy (on the same VM) needs access. Block 8333 from the public internet at your cloud provider’s firewall.
• Expose only the proxy ports. 9443 / 443 (HTTPS) for TLS-enabled installs, or 9080 / 80 for insecure. See the Reverse Proxy page.
• Use real TLS certs. Let’s Encrypt via --cert-source certbot, or bring your own with --cert-source user. Self-signed is fine for evaluation but gives browser warnings.
• Rotate the proxy admin password. Set a strong one at init; change it with norsk-ctl user set norsk-studio-admin later.
• Restrict SSH with cloud-provider SSH-over-IAP or an equivalent. The bootstrap flow doesn’t require SSH for normal operation.

Managing remotely

The norsk-ctl CLI is a local admin tool — it always talks to a daemon on the same machine. To manage a cloud instance, either:

• Use the web UI behind the proxy (the normal remote path, authenticated via oauth2-proxy), or
• SSH to the VM and run norsk-ctl there.