@norskvideo/ctl-dev-kit 0.2.75 → 0.2.76

package/conventions/check-drift.ts

@@ -292,6 +292,12 @@ export interface CanonicalBytes {
   integration: string;
   /** conventions/demo.sh — the scripts/demo shim a product with tests/demo.spec.ts carries. */
   demoShim: string;
+  /** conventions/server-install.sh and server-uninstall.sh — the server
+   *  deployment kit's deployment/install.sh and uninstall.sh. Gated only for a
+   *  copy that names its canonical source, so a product's own hand-written
+   *  install.sh at that path is left to it. */
+  serverInstall?: string;
+  serverUninstall?: string;
   /** doc-guide/with-display.sh — the X-display wrapper BOTH docs workflows invoke
    *  as `scripts/with-display.sh`. Gated because the workflow is: an ungated
    *  hand copy is how build-docs.yml came to fail in both turnkeys, which never
@@ -312,6 +318,30 @@ export interface CanonicalBytes {
   bumpSdkApp?: string;
 }
 
+export const SERVER_KIT_COPIES = [
+  { rel: "deployment/install.sh", source: "server-install.sh", key: "serverInstall" },
+  { rel: "deployment/uninstall.sh", source: "server-uninstall.sh", key: "serverUninstall" },
+] as const;
+
+/** A copy names its source in its header; a product's own script does not. */
+export const isServerKitCopy = (content: string, source: string): boolean =>
+  content.includes(`@norskvideo/ctl-dev-kit conventions/${source}`);
+
+export function serverKitProblems(repoRoot: string, canonical: CanonicalBytes): string[] {
+  const problems: string[] = [];
+  for (const { rel, source, key } of SERVER_KIT_COPIES) {
+    const expected = canonical[key];
+    const path = join(repoRoot, rel);
+    if (expected === undefined || !existsSync(path)) continue;
+    const actual = readFileSync(path, "utf8");
+    if (!isServerKitCopy(actual, source) || actual === expected) continue;
+    problems.push(
+      `${rel} has drifted from @norskvideo/ctl-dev-kit conventions/${source} (${firstDiffLine(actual, expected)}). ${RESYNC}`,
+    );
+  }
+  return problems;
+}
+
 // 05-demo s6: a product that has a demo (tests/demo.spec.ts) exposes it the
 // shared way — scripts/demo, the verbatim executable shim that re-execs under
 // the nix dev shell and delegates to `bun run demo`, and the package.json
@@ -893,6 +923,7 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes, opts: Ch
   for (const p of docsSiteExposureProblems(existsSync(siteWorkflowPath), hasDocsSite(repoRoot), opts.repoName)) push(p);
 
   for (const p of demoProblems(repoRoot, canonical.demoShim)) push(p);
+  for (const p of serverKitProblems(repoRoot, canonical)) push(p);
   for (const p of productLogsProblems(repoRoot)) push(p);
   for (const p of bunVersionProblems(repoRoot, canonical.ctlShell)) push(p);
   for (const p of ctlPinProblems(repoRoot)) push(p);
@@ -922,6 +953,8 @@ if (import.meta.main) {
     smoke: readFileSync(join(import.meta.dir, "smoke.yml"), "utf8"),
     integration: readFileSync(join(import.meta.dir, "integration.yml"), "utf8"),
     demoShim: readFileSync(join(import.meta.dir, "demo.sh"), "utf8"),
+    serverInstall: readFileSync(join(import.meta.dir, "server-install.sh"), "utf8"),
+    serverUninstall: readFileSync(join(import.meta.dir, "server-uninstall.sh"), "utf8"),
     flakeSdkApp: readFileSync(join(import.meta.dir, "..", "build", "flake.sdk-app.nix"), "utf8"),
     checksSdkApp: readFileSync(join(import.meta.dir, "checks.sdk-app.yml"), "utf8"),
     bumpSdkApp: readFileSync(join(import.meta.dir, "bump.sdk-app.yml"), "utf8"),

package/conventions/server-install.sh

@@ -0,0 +1,291 @@
+#!/usr/bin/env bash
+# Install this product on a server, from a release directory written by
+# deployment/package-release.sh. Takes a box with nothing of ours on it to a
+# running instance; uninstall.sh (beside it) takes it back.
+#
+# Runs ON the server, as a sudo-capable user, from the release directory:
+#
+#   export NORSK_ADMIN_PASSWORD=...   # first install only: the web login (>=8 chars, >=1 digit)
+#   export <PARAMETER>=...            # any launch parameter the template declares
+#   bash install.sh --license /path/to/licence.json
+#
+# Launch parameters are the product template's own: every parameter it declares
+# is passed when a variable of that name is set, a required one must be, and
+# the rest take the template's defaults. Secrets come from the environment,
+# never the command line.
+#
+# Idempotent: each step checks before it acts, so a re-run after a failure picks
+# up where it stopped, and a re-run with a newer release replaces the product (a
+# stored template never sees a new image otherwise) and relaunches the instance
+# in the same working directory, so its media and settings survive.
+#
+# Access (ACCESS, default tunnel): the web page stays off the public network and
+# is reached over SSH, the shape a host that admits only SSH and media needs:
+#   ssh -L 8443:127.0.0.1:8443 <user>@<host>    # then https://localhost:8443
+# The proxy listens on PROXY_PORT (8443), the port the tunnel forwards, so the
+# URLs norsk-ctl advertises are the ones the browser uses. ACCESS=public serves
+# 443 to the world instead, at PUBLIC_HOST (default the detected public IP).
+#
+# Options (environment):
+#   INSTANCE_ID                        default: the product's name
+#   CERT_SOURCE, DOMAIN, CERT_EMAIL    passed to the norsk-ctl installer
+#   RELAUNCH=1                         replace a running instance, e.g. to apply
+#                                      a changed parameter
+#
+# Copied verbatim from @norskvideo/ctl-dev-kit conventions/server-install.sh and
+# drift-gated: edit the dev-kit source and re-sync, never this copy.
+set -euo pipefail
+
+CTL=(sudo -u norsk env NORSK_CTL_CONFIG_DIR=/etc/norsk-ctl NORSK_CTL_STATE_DIR=/var/lib/norsk-ctl
+  NORSK_CTL_LOG_DIR=/var/log/norsk-ctl norsk-ctl)
+CTL_WAIT_SECONDS="${CTL_WAIT_SECONDS:-90}"
+
+info() { printf '\n==> %s\n' "$*"; }
+oops() {
+  printf 'error: %s\n' "$*" >&2
+  exit 1
+}
+# As the service user with its configuration: the installer adds us to the
+# norsk group, but not in this login session, and sudo drops the profile.d
+# environment the CLI reads.
+ctl() { "${CTL[@]}" "$@"; }
+
+# Bounded by the clock, not by attempts: a CLI call against a daemon that is
+# down can itself take many seconds.
+wait_for_ctl() {
+  local deadline=$((SECONDS + CTL_WAIT_SECONDS))
+  while [ "${SECONDS}" -lt "${deadline}" ]; do
+    timeout 5 "${CTL[@]}" product list >/dev/null 2>&1 && return 0
+    sleep 1
+  done
+  oops "norsk-ctl did not come back within ${CTL_WAIT_SECONDS}s (journalctl -u norsk-ctl)"
+}
+
+# Appends `key: value` to a YAML file unless the key is set. On its own line
+# whether or not the file ends in a newline: norsk-ctl's init writes
+# config.yaml without one, and a key joined to the last line stops the daemon.
+ensure_config_line() {
+  local key=$1 value=$2 file=$3
+  sudo grep -q "^${key}:" "${file}" && return 1
+  printf '\n%s: %s\n' "${key}" "${value}" | sudo tee -a "${file}" >/dev/null
+}
+
+# The template's parameters (`template show -o json` on stdin) as --param
+# arguments, NUL-separated: a parameter is passed when a variable of its name is
+# set and non-empty; INSTANCE_NAME defaults to the instance id. Fails naming
+# every required parameter that is unset.
+launch_params() {
+  local name required value missing=()
+  while IFS=$'\t' read -r name required; do
+    value="${!name:-}"
+    [ -z "${value}" ] && [ "${name}" = INSTANCE_NAME ] && value="${INSTANCE_ID}"
+    if [ -n "${value}" ]; then
+      printf -- '--param\0%s=%s\0' "${name}" "${value}"
+    elif [ "${required}" = true ]; then
+      missing+=("${name}")
+    fi
+  done < <(jq -r '.parameters[] | [.name, (.required // false | tostring)] | @tsv')
+  [ "${#missing[@]}" = 0 ] || oops "export the required launch parameters: ${missing[*]}"
+}
+
+main() {
+  local here
+  here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  # shellcheck source=/dev/null
+  . "${here}/release.env" # PRODUCT, IMAGE, IMAGE_ARCH, IMAGE_TAR, CTL_VERSION, RELEASE_COMMIT
+
+  local license=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --license)
+        license=$2
+        shift
+        ;;
+      *)
+        echo "unknown argument $1" >&2
+        exit 2
+        ;;
+    esac
+    shift
+  done
+  INSTANCE_ID="${INSTANCE_ID:-${PRODUCT}}"
+  local access="${ACCESS:-tunnel}" proxy_port="${PROXY_PORT:-8443}"
+  case "${access}" in
+    tunnel | public) ;;
+    *)
+      echo "ACCESS must be tunnel or public, not ${access}" >&2
+      exit 2
+      ;;
+  esac
+  local record_dir="/var/lib/${PRODUCT}-install"
+  local record="${record_dir}/record.env"
+
+  info "Preflight"
+  [ -n "${license}" ] || oops "missing --license"
+  [ -r "${license}" ] || oops "cannot read ${license}"
+  # Docker is the box's own: the norsk-ctl installer would add it when missing,
+  # and uninstall.sh could then not tell whose it was.
+  for tool in curl jq docker tar gzip; do
+    command -v "${tool}" >/dev/null || oops "${tool} is required"
+  done
+  sudo -n true 2>/dev/null || sudo -v
+  local arch
+  case "$(uname -m)" in
+    x86_64) arch=amd64 ;;
+    aarch64 | arm64) arch=arm64 ;;
+    *) arch=unknown ;;
+  esac
+  [ "${arch}" = "${IMAGE_ARCH}" ] || oops "this release is ${IMAGE_ARCH}, this server is ${arch}"
+
+  # What the box looked like before us, so uninstall.sh restores exactly that.
+  # Written once: a re-run must not record our own changes as the baseline.
+  if ! sudo test -f "${record}"; then
+    info "Recording the baseline (${record})"
+    local invoking_user="${SUDO_USER:-$(id -un)}"
+    sudo install -d -m 0755 "${record_dir}"
+    {
+      printf 'RECORDED_AT=%q\n' "$(date -Is)"
+      printf 'INVOKING_USER=%q\n' "${invoking_user}"
+      printf 'USER_GROUPS_BEFORE=%q\n' "$(id -nG "${invoking_user}")"
+      printf 'CTL_PREINSTALLED=%q\n' "$(command -v norsk-ctl >/dev/null && echo 1 || echo 0)"
+      printf 'IMAGES_BEFORE=%q\n' "$(sudo docker image ls -q --no-trunc | sort -u | tr '\n' ' ')"
+      for key in net.core.rmem_max net.core.wmem_max net.core.rmem_default net.core.wmem_default \
+        net.core.netdev_max_backlog net.ipv4.tcp_rmem net.ipv4.tcp_wmem net.ipv4.tcp_congestion_control; do
+        printf 'SYSCTL_%s=%q\n' "$(echo "${key}" | tr '.' '_')" "$(sysctl -n "${key}" | tr '\t' ' ')"
+      done
+    } | sudo tee "${record}" >/dev/null
+  fi
+
+  if ! command -v norsk-ctl >/dev/null; then
+    info "norsk-ctl ${CTL_VERSION} (public installer)"
+    : "${NORSK_ADMIN_PASSWORD:?export NORSK_ADMIN_PASSWORD (>=8 chars, >=1 digit)}"
+    export NORSK_ADMIN_PASSWORD
+    local installer
+    installer="$(mktemp)"
+    curl -fsSL https://s3.eu-west-1.amazonaws.com/norsk.video/norsk-ctl/install.sh -o "${installer}"
+    local flags=()
+    [ -n "${CERT_SOURCE:-}" ] && flags+=(--cert-source "${CERT_SOURCE}")
+    [ -n "${DOMAIN:-}" ] && flags+=(--domain "${DOMAIN}")
+    [ -n "${CERT_EMAIL:-}" ] && flags+=(--cert-email "${CERT_EMAIL}")
+    if [ "${access}" = tunnel ]; then
+      flags+=(--public-host localhost --proxy-port "${proxy_port}" --no-http-redirect)
+      if grep -q -- '--bind-address)' "${installer}"; then
+        flags+=(--bind-address 127.0.0.1)
+      else
+        echo "warning: this norsk-ctl cannot bind to loopback; its proxy and API listen on every interface" >&2
+      fi
+    else
+      flags+=(--public-host "${PUBLIC_HOST:-auto}")
+    fi
+    bash "${installer}" --server --version "${CTL_VERSION}" --license "${license}" "${flags[@]}" --pull-images --yes
+    rm -f "${installer}"
+  fi
+  # The public installer leaves a running norsk-ctl as it is, so a box set up by
+  # an earlier release is upgraded here, as norsk-ctl's upgrade guide does it:
+  # back up its config and state, swap the binary, restart the service. The
+  # daemon's SIGTERM stops only itself; the proxy and instances keep running.
+  local installed_ctl
+  installed_ctl="$(norsk-ctl --version)"
+  if [ "${installed_ctl}" != "${CTL_VERSION}" ]; then
+    info "Upgrading norsk-ctl ${installed_ctl} -> ${CTL_VERSION}"
+    local plat base bin want backup
+    plat="linux-$([ "${arch}" = amd64 ] && echo x64 || echo arm64)"
+    base="https://s3.eu-west-1.amazonaws.com/norsk.video/norsk-ctl/${CTL_VERSION}"
+    bin="$(mktemp)"
+    curl -fsSL "${base}/norsk-ctl-${CTL_VERSION}-${plat}" -o "${bin}"
+    want="$(curl -fsSL "${base}/norsk-ctl-${CTL_VERSION}-${plat}.sha256" | awk '{print $1}')"
+    [ "$(sha256sum "${bin}" | awk '{print $1}')" = "${want}" ] || oops "norsk-ctl ${CTL_VERSION} failed its checksum"
+    backup="${record_dir}/norsk-ctl-${installed_ctl}.tar.gz"
+    sudo tar -czf "${backup}" -C / etc/norsk-ctl var/lib/norsk-ctl
+    echo "backed up norsk-ctl's config and state to ${backup}"
+    sudo install -o norsk -g norsk -m 0755 "${bin}" "/opt/norsk-ctl/bin/norsk-ctl-${CTL_VERSION}"
+    rm -f "${bin}"
+    sudo ln -sfn "/opt/norsk-ctl/bin/norsk-ctl-${CTL_VERSION}" /usr/local/bin/norsk-ctl
+    sudo systemctl restart norsk-ctl
+    wait_for_ctl
+  fi
+
+  # Behind a tunnel, norsk-ctl's shared MoQ relay would advertise its preview
+  # URLs from the tunnel's localhost, where no browser can reach them over UDP.
+  # An instance's own preview listener, given the box's public address, can.
+  local relay_dropin="/etc/systemd/system/norsk-ctl.service.d/${PRODUCT}.conf"
+  if [ "${access}" = tunnel ] && ! sudo test -f "${relay_dropin}"; then
+    info "Turning off norsk-ctl's shared MoQ relay"
+    sudo install -d /etc/systemd/system/norsk-ctl.service.d
+    printf '[Service]\nEnvironment=NORSK_CTL_MOQ_RELAY_ENABLE=0\n' | sudo tee "${relay_dropin}" >/dev/null
+    sudo systemctl daemon-reload
+    sudo systemctl restart norsk-ctl
+    wait_for_ctl
+    sudo docker rm -f norsk-moq-relay >/dev/null 2>&1 || true
+  fi
+
+  # Behind a tunnel the proxy and the daemon's API stay on loopback, on a
+  # norsk-ctl that can say so. An install made before it could gets the setting
+  # here; the restart republishes the proxy on it.
+  if [ "${access}" = tunnel ] && norsk-ctl init --help 2>/dev/null | grep -q -- '--bind-address' &&
+    ensure_config_line bindAddress 127.0.0.1 /etc/norsk-ctl/config.yaml; then
+    info "Bound the proxy and the daemon's API to loopback"
+    sudo systemctl restart norsk-ctl
+    wait_for_ctl
+  fi
+  local staged_license
+  staged_license="/etc/norsk-ctl/licenses/$(basename "${license}")"
+  sudo test -f "${staged_license}" || sudo install -m 0640 -o norsk -g norsk "${license}" "${staged_license}"
+
+  info "Product image ${IMAGE}"
+  sudo docker image inspect "${IMAGE}" >/dev/null 2>&1 || gunzip -c "${here}/${IMAGE_TAR}" | sudo docker load
+
+  info "Product ${PRODUCT}"
+  local registered
+  registered="$(ctl product list -o json |
+    jq -r --arg p "${PRODUCT}" '[.. | objects | select(has("spec") and .name == $p) | .spec.image][0] // ""')"
+  if [ -n "${registered}" ] && [ "${registered}" != "${IMAGE}" ]; then
+    # A stored template is fetched once at `product add`; a new image reaches
+    # nothing until the product is added again.
+    info "Replacing ${PRODUCT} (${registered} -> ${IMAGE})"
+    # Not purged: the relaunch below takes the same working directory.
+    if ctl instance exists "${INSTANCE_ID}" >/dev/null 2>&1; then ctl instance delete "${INSTANCE_ID}"; fi
+    for t in $(ctl template list -o json |
+      jq -r --arg p "${PRODUCT}" '.productTemplates[] | select(.source.productName == $p) | .name'); do
+      ctl template remove "${t}"
+    done
+    ctl product remove "${PRODUCT}"
+    registered=""
+  fi
+  [ -n "${registered}" ] || ctl product add --license-file "${staged_license}" --image "${IMAGE}"
+
+  info "Instance ${INSTANCE_ID}"
+  local template
+  template="$(ctl template list -o json |
+    jq -r --arg p "${PRODUCT}" '.productTemplates[] | select(.source.kind == "product-default" and .source.productName == $p) | .name' |
+    head -1)"
+  [ -n "${template}" ] || oops "no product-default template for ${PRODUCT}"
+  # Through files, not a pipe: launch_params then runs in this shell, and a
+  # missing required parameter stops the install before the instance is touched.
+  local shown params=()
+  shown="$(mktemp)"
+  ctl template show "${template}" -o json >"${shown}"
+  launch_params <"${shown}" >"${shown}.args"
+  mapfile -d '' params <"${shown}.args"
+  rm -f "${shown}" "${shown}.args"
+  if [ "${RELAUNCH:-}" = 1 ] && ctl instance exists "${INSTANCE_ID}" >/dev/null 2>&1; then
+    ctl instance delete "${INSTANCE_ID}"
+  fi
+  if ! ctl instance exists "${INSTANCE_ID}" >/dev/null 2>&1; then
+    # TODO: --param puts secrets on a process argv for the length of the call;
+    # move them to an env-file once ctl takes one.
+    ctl instance launch-template "${INSTANCE_ID}" --template "${template}" "${params[@]}"
+  fi
+
+  info "Done (release ${RELEASE_COMMIT})"
+  ctl instance list
+  echo
+  if [ "${access}" = tunnel ]; then
+    echo "Reach it with: ssh -L ${proxy_port}:127.0.0.1:${proxy_port} $(id -un)@<this host>, then https://localhost:${proxy_port}"
+    echo "Open inbound only the product's media ports (docs/administering.md lists them)."
+  else
+    echo "Open inbound: 443/tcp and the product's media ports (docs/administering.md lists them)."
+  fi
+}
+
+if [ "${BASH_SOURCE[0]}" = "$0" ]; then main "$@"; fi

package/conventions/server-uninstall.sh

@@ -0,0 +1,182 @@
+#!/usr/bin/env bash
+# Take a server back to how it was before install.sh: the product, its
+# instances and images, then norsk-ctl itself with everything its installer put
+# on the box. Docker and anything else the box already had stay.
+#
+#   bash uninstall.sh [--keep-ctl | --remove-ctl] [--yes]
+#
+# Runs from the release directory (release.env names the product). norsk-ctl is
+# removed only when install.sh installed it (its baseline record says so) or no
+# record exists, and never while another product is still registered.
+# --keep-ctl removes only this product; --remove-ctl removes norsk-ctl even
+# though it was there before install.sh.
+#
+# Ends by listing anything left behind, and exits non-zero if there is any.
+#
+# Copied verbatim from @norskvideo/ctl-dev-kit conventions/server-uninstall.sh
+# and drift-gated: edit the dev-kit source and re-sync, never this copy.
+set -euo pipefail
+
+info() { printf '\n==> %s\n' "$*"; }
+oops() {
+  printf 'error: %s\n' "$*" >&2
+  exit 1
+}
+ctl() {
+  sudo -u norsk env NORSK_CTL_CONFIG_DIR=/etc/norsk-ctl NORSK_CTL_STATE_DIR=/var/lib/norsk-ctl \
+    NORSK_CTL_LOG_DIR=/var/log/norsk-ctl norsk-ctl "$@"
+}
+have_ctl() { command -v norsk-ctl >/dev/null && systemctl is-active --quiet norsk-ctl; }
+
+# Whether ctl goes too: asked to keep it, or it predates install.sh and nobody
+# asked for it gone.
+removes_ctl() {
+  local keep=$1 remove=$2 preinstalled=$3
+  [ "${keep}" = 1 ] && return 1
+  [ "${preinstalled}" = 1 ] && [ "${remove}" != 1 ] && return 1
+  return 0
+}
+
+main() {
+  local here
+  here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  # shellcheck source=/dev/null
+  . "${here}/release.env" # PRODUCT, IMAGE
+  local keep_ctl=0 remove_ctl_flag=0 assume_yes=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --keep-ctl) keep_ctl=1 ;;
+      --remove-ctl) remove_ctl_flag=1 ;;
+      --yes | -y) assume_yes=1 ;;
+      *)
+        echo "unknown argument $1" >&2
+        exit 2
+        ;;
+    esac
+    shift
+  done
+  local record_dir="/var/lib/${PRODUCT}-install"
+  local record="${record_dir}/record.env"
+
+  sudo -n true 2>/dev/null || sudo -v
+  if sudo test -f "${record}"; then
+    # shellcheck source=/dev/null
+    . <(sudo cat "${record}")
+  else
+    echo "no baseline record (${record}): restoring stock defaults where the record would have said" >&2
+  fi
+  local remove_ctl=0
+  removes_ctl "${keep_ctl}" "${remove_ctl_flag}" "${CTL_PREINSTALLED:-0}" && remove_ctl=1
+
+  if [ "${assume_yes}" != 1 ]; then
+    printf 'Remove %s%s from this server? [y/N] ' "${PRODUCT}" "$([ "${remove_ctl}" = 1 ] && echo ' and norsk-ctl')"
+    local answer
+    read -r answer
+    [ "${answer}" = y ] || [ "${answer}" = Y ] || exit 1
+  fi
+
+  if have_ctl; then
+    info "Product ${PRODUCT}"
+    for id in $(ctl instance list -o json | jq -r --arg p "${PRODUCT}" '.instances[] | select(.productName == $p) | .id'); do
+      ctl instance delete "${id}" --purge
+    done
+    for t in $(ctl template list -o json |
+      jq -r --arg p "${PRODUCT}" '.productTemplates[] | select(.source.productName == $p) | .name'); do
+      ctl template remove "${t}"
+    done
+    if ctl product exists "${PRODUCT}" >/dev/null 2>&1; then ctl product remove "${PRODUCT}"; fi
+  fi
+  sudo docker rm -f "norsk-product-${PRODUCT}" >/dev/null 2>&1 || true
+
+  local proxy_images=""
+  if [ "${remove_ctl}" = 1 ]; then
+    if have_ctl; then
+      local others
+      others="$(ctl product list -o json | jq -r '[.. | objects | select(has("spec")) | .name] | join(" ")')"
+      [ -z "${others}" ] || oops "other products are registered (${others}); re-run with --keep-ctl"
+    fi
+
+    info "norsk-ctl"
+    # The proxy's images are whatever ctl pulled; read them before the
+    # containers go.
+    proxy_images="$(sudo docker ps -a --filter name=norsk-proxy --format '{{.Image}}' | sort -u)"
+    if have_ctl; then ctl shutdown || true; fi
+    sudo systemctl disable --now norsk-ctl.service 2>/dev/null || true
+    sudo rm -f /etc/systemd/system/norsk-ctl.service
+    sudo rm -rf /etc/systemd/system/norsk-ctl.service.d
+    sudo systemctl daemon-reload
+    sudo docker rm -f norsk-proxy norsk-proxy-oauth2 norsk-moq-relay >/dev/null 2>&1 || true
+    sudo docker network rm norsk-net >/dev/null 2>&1 || true
+
+    local working_dir
+    working_dir="$(sudo awk '/^defaultWorkingDirectory:/ { print $2 }' /etc/norsk-ctl/config.yaml 2>/dev/null || true)"
+    sudo rm -rf /etc/norsk-ctl /var/lib/norsk-ctl /var/log/norsk-ctl /opt/norsk-ctl \
+      /usr/local/bin/norsk-ctl /etc/profile.d/norsk-ctl.sh "${working_dir:-/var/norsk-ctl}"
+    # TODO: certbot (--cert-source certbot): delete the certificate and the
+    # renewal timer the installer set up.
+
+    info "Kernel tuning"
+    sudo rm -f /etc/sysctl.d/90-norsk-tuning.conf
+    # Stock Ubuntu 24.04 values stand in when there is no record. Applied before
+    # `sysctl --system`, so the box's own sysctl.d settings still win.
+    restore() { sudo sysctl -q -w "$1=$2" >/dev/null || echo "warning: could not restore $1" >&2; }
+    restore net.core.rmem_max "${SYSCTL_net_core_rmem_max:-212992}"
+    restore net.core.wmem_max "${SYSCTL_net_core_wmem_max:-212992}"
+    restore net.core.rmem_default "${SYSCTL_net_core_rmem_default:-212992}"
+    restore net.core.wmem_default "${SYSCTL_net_core_wmem_default:-212992}"
+    restore net.core.netdev_max_backlog "${SYSCTL_net_core_netdev_max_backlog:-1000}"
+    restore net.ipv4.tcp_rmem "${SYSCTL_net_ipv4_tcp_rmem:-4096 131072 6291456}"
+    restore net.ipv4.tcp_wmem "${SYSCTL_net_ipv4_tcp_wmem:-4096 16384 4194304}"
+    restore net.ipv4.tcp_congestion_control "${SYSCTL_net_ipv4_tcp_congestion_control:-cubic}"
+    sudo sysctl -q --system >/dev/null
+
+    info "Service user"
+    # Deleting the norsk group also takes every member out of it. Docker
+    # membership the installer granted goes only when the record shows it was
+    # not there before.
+    if [ -n "${INVOKING_USER:-}" ] && ! grep -qw docker <<<"${USER_GROUPS_BEFORE:-docker}"; then
+      sudo gpasswd -d "${INVOKING_USER}" docker >/dev/null || true
+    fi
+    if id -u norsk >/dev/null 2>&1; then sudo userdel -r norsk 2>/dev/null || true; fi
+    if getent group norsk >/dev/null; then sudo groupdel norsk || true; fi
+  fi
+
+  info "Images"
+  # Ours, the media and Studio images its instances ran, and the proxy's;
+  # anything the record shows was here before stays.
+  local product_repo="${IMAGE%:*}" id
+  for ref in $(sudo docker image ls --format '{{.Repository}}:{{.Tag}}' |
+    grep -E "^(${product_repo}|norskvideo/norsk|norskvideo/norsk-studio|norskvideo/norsk-moq-relay):" || true) ${proxy_images}; do
+    id="$(sudo docker image inspect -f '{{.Id}}' "${ref}" 2>/dev/null)" || continue
+    grep -qw "${id}" <<<"${IMAGES_BEFORE:-}" && continue
+    sudo docker image rm "${ref}" >/dev/null || echo "warning: could not remove ${ref}" >&2
+  done
+
+  sudo rm -rf "${record_dir}"
+
+  info "Left behind"
+  local left=0
+  check() {
+    if eval "$2"; then
+      echo "  $1"
+      left=1
+    fi
+  }
+  check "image ${product_repo}" "sudo docker image ls -q '${product_repo}' | grep -q ."
+  check "container norsk-product-${PRODUCT}" "sudo docker ps -aq --filter name=norsk-product-${PRODUCT} | grep -q ."
+  if [ "${remove_ctl}" = 1 ]; then
+    for p in /etc/norsk-ctl /var/lib/norsk-ctl /var/log/norsk-ctl /opt/norsk-ctl /usr/local/bin/norsk-ctl \
+      /etc/profile.d/norsk-ctl.sh /etc/sysctl.d/90-norsk-tuning.conf /etc/systemd/system/norsk-ctl.service \
+      /etc/systemd/system/norsk-ctl.service.d; do
+      check "${p}" "sudo test -e '${p}'"
+    done
+    check "user norsk" "id -u norsk >/dev/null 2>&1"
+    check "group norsk" "getent group norsk >/dev/null"
+    check "docker network norsk-net" "sudo docker network inspect norsk-net >/dev/null 2>&1"
+    check "norsk containers" "sudo docker ps -a --format '{{.Names}}' | grep -q '^norsk-'"
+  fi
+  [ "${left}" = 0 ] && echo "  nothing"
+  exit "${left}"
+}
+
+if [ "${BASH_SOURCE[0]}" = "$0" ]; then main "$@"; fi

package/conventions/sync-drift.ts

@@ -44,6 +44,7 @@ import {
   GITIGNORE_END,
   hasDocsSite,
   importsCtlShell,
+  isServerKitCopy,
   PRODUCT_LINE,
   PRODUCT_SENTINEL,
   type ProductShape,
@@ -53,6 +54,7 @@ import {
   RUNNER_LINE,
   resolveRepoName,
   resolveShape,
+  SERVER_KIT_COPIES,
   splitAtMarkers,
 } from "./check-drift.ts";
 
@@ -334,6 +336,18 @@ function syncDemoShim(repoRoot: string, canonical: string, r: SyncReport): void
   chmodSync(path, 0o755);
 }
 
+// The server kit's scripts: only a copy (it names its source) is rewritten; a
+// product's own install.sh at that path is the product's.
+export function syncServerKit(repoRoot: string, canonical: CanonicalBytes, r: SyncReport): void {
+  for (const { rel, source, key } of SERVER_KIT_COPIES) {
+    const expected = canonical[key];
+    const path = join(repoRoot, rel);
+    if (expected === undefined || !existsSync(path) || !isServerKitCopy(readFileSync(path, "utf8"), source)) continue;
+    writeIfChanged(path, expected, rel, r.written);
+    chmodSync(path, 0o755);
+  }
+}
+
 // Both docs workflows run `bash scripts/with-display.sh ...`. It stays a
 // repo-local executable (the package.json guide scripts invoke it by that path),
 // so a repo that carries a docs workflow gets the canonical copy written here
@@ -478,6 +492,7 @@ export function syncDrift(
   syncGitignore(repoRoot, canonical.gitignoreCore, r);
   syncDprint(repoRoot, canonical.dprint, r);
   syncDemoShim(repoRoot, canonical.demoShim, r);
+  syncServerKit(repoRoot, canonical, r);
   syncWithDisplay(repoRoot, canonical.withDisplay, r);
   syncDocsTheme(repoRoot, r);
   syncPublishDocsSite(repoRoot, canonical.publishDocsSite, opts.repoName, r);
@@ -508,6 +523,8 @@ if (import.meta.main) {
     smoke: readFileSync(join(dir, "smoke.yml"), "utf8"),
     integration: readFileSync(join(dir, "integration.yml"), "utf8"),
     demoShim: readFileSync(join(dir, "demo.sh"), "utf8"),
+    serverInstall: readFileSync(join(dir, "server-install.sh"), "utf8"),
+    serverUninstall: readFileSync(join(dir, "server-uninstall.sh"), "utf8"),
     flakeSdkApp: readFileSync(join(dir, "..", "build", "flake.sdk-app.nix"), "utf8"),
     checksSdkApp: readFileSync(join(dir, "checks.sdk-app.yml"), "utf8"),
     bumpSdkApp: readFileSync(join(dir, "bump.sdk-app.yml"), "utf8"),

package/create-product/canon.ts

@@ -33,6 +33,10 @@ export interface Canon {
   invariantsTemplate: string;
   /** conventions/demo.sh, emitted as scripts/demo. */
   demoShim: string;
+  /** conventions/server-install.sh and server-uninstall.sh, emitted as
+   *  deployment/install.sh and deployment/uninstall.sh. */
+  serverInstall: string;
+  serverUninstall: string;
   /** doc-guide/with-display.sh, emitted as scripts/with-display.sh — the docs
    *  workflow invokes it by that repo-local path. */
   withDisplay: string;
@@ -58,6 +62,8 @@ export function loadCanon(): Canon {
     gitignoreCore: readFileSync(join(conventionsDir, "gitignore.core"), "utf8"),
     invariantsTemplate: readFileSync(join(import.meta.dir, "..", "testing", "INVARIANTS.template.md"), "utf8"),
     demoShim: readFileSync(join(conventionsDir, "demo.sh"), "utf8"),
+    serverInstall: readFileSync(join(conventionsDir, "server-install.sh"), "utf8"),
+    serverUninstall: readFileSync(join(conventionsDir, "server-uninstall.sh"), "utf8"),
   };
 }
 

package/create-product/server-kit.ts

@@ -0,0 +1,95 @@
+// The server deployment kit: how a turnkey reaches a customer's own server and
+// leaves it again. install.sh and uninstall.sh are product-independent (they
+// read the product from release.env and its launch parameters from the stored
+// template), so they are canonical copies of conventions/server-*.sh. What is
+// this product's is the image the release packs.
+import type { ShapeContext } from "./create-product.ts";
+
+export function packageReleaseSh(ctx: ShapeContext): string {
+  return `#!/usr/bin/env bash
+# Build a release for a server: the product image as a portable tar, install.sh
+# and uninstall.sh, and release.env naming what they install. The image is in
+# no registry; the server pulls the media and Studio images and norsk-ctl
+# itself.
+#
+#   bun run package-release [-- <out-dir>]                        # default release/
+#   SKIP_BUILD=1 IMAGE_TAG=<repo:tag> bun run package-release      # an existing image
+#
+# Then copy the directory to the server and run install.sh there (its header
+# says how), e.g.
+#   tar -C release -czf - . | ssh <host> 'mkdir -p ${ctx.name}-release && tar -C ${ctx.name}-release -xzf -'
+set -euo pipefail
+
+repo="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+out="\${1:-\${repo}/release}"
+cd "\${repo}"
+commit="$(git describe --always --dirty)"
+# Tagged by commit: install.sh tells releases apart by tag, and a reused tag
+# (\`:dev\`) would leave a server on the build it already has. The licence names
+# the repository, not the tag.
+export IMAGE_TAG="\${IMAGE_TAG:-${ctx.name}:\${commit}}"
+[ -n "\${SKIP_BUILD:-}" ] || bun run build:image
+# The tested norsk-ctl is the one the dev shell pins.
+ctl_version="$(sed -n 's/^ *ctlVersion = "\\(.*\\)";/\\1/p' flake.nix)"
+[ -n "\${ctl_version}" ] || {
+  echo "no ctlVersion in flake.nix" >&2
+  exit 1
+}
+
+rm -rf "\${out}"
+mkdir -p "\${out}"
+docker save "\${IMAGE_TAG}" | gzip -1 >"\${out}/image.tar.gz"
+cp deployment/install.sh deployment/uninstall.sh "\${out}/"
+{
+  printf 'PRODUCT=%q\\n' ${ctx.name}
+  printf 'IMAGE=%q\\n' "\${IMAGE_TAG}"
+  printf 'IMAGE_ARCH=%q\\n' "$(docker image inspect -f '{{.Architecture}}' "\${IMAGE_TAG}")"
+  printf 'IMAGE_TAR=%q\\n' image.tar.gz
+  printf 'CTL_VERSION=%q\\n' "\${ctl_version}"
+  printf 'RELEASE_COMMIT=%q\\n' "\${commit}"
+} >"\${out}/release.env"
+echo "release in \${out}"
+`;
+}
+
+export function shipImageSh(ctx: ShapeContext): string {
+  return `#!/usr/bin/env bash
+# Build the ${ctx.name} image and load it into a remote host's Docker, for a
+# host that cannot pull it (the image is in no registry). norsk-ctl on that host
+# then adds and launches it from the local copy: \`product add\` and the launch
+# both treat a failed pull as "use the local image". For a customer's server,
+# package-release.sh is the whole kit; this is the quick route for a dev box.
+#
+#   bun run ship-image -- <ssh-host>               # build, then ship
+#   SKIP_BUILD=1 bun run ship-image -- <ssh-host>  # ship the existing image
+set -euo pipefail
+
+host="\${1:?usage: ship-image.sh <ssh-host>}"
+export IMAGE_TAG="\${IMAGE_TAG:-${ctx.name}:dev}"
+cd "$(dirname "\${BASH_SOURCE[0]}")/.."
+
+[ -n "\${SKIP_BUILD:-}" ] || bun run build:image
+
+# An image built for another architecture loads without complaint and then
+# fails at launch, so refuse it here.
+local_arch="$(docker image inspect -f '{{.Architecture}}' "\${IMAGE_TAG}")"
+case "$(ssh "\${host}" uname -m)" in
+  x86_64) remote_arch=amd64 ;;
+  aarch64 | arm64) remote_arch=arm64 ;;
+  *) remote_arch=unknown ;;
+esac
+if [ "\${local_arch}" != "\${remote_arch}" ]; then
+  echo "\${IMAGE_TAG} is \${local_arch} but \${host} is \${remote_arch}: build on a \${remote_arch} machine" >&2
+  exit 1
+fi
+
+echo "shipping \${IMAGE_TAG} to \${host}"
+docker save "\${IMAGE_TAG}" | gzip | ssh "\${host}" 'gunzip | docker load'
+echo "loaded. On \${host}: norsk-ctl product add --image \${IMAGE_TAG} --license-file <licence>"
+`;
+}
+
+export const SERVER_KIT_GITIGNORE = `# A release (bun run package-release): the image tar and the scripts, built for
+# a server, never source.
+release/
+`;

package/create-product/turnkey.ts

@@ -38,6 +38,7 @@ import {
 } from "./features/dashboard.ts";
 import { CONFIG_SCREEN_URL, FRONTEND_SERVER_BLOCK, frontendFiles } from "./features/frontend.ts";
 import { VIEWS_PROXY_EXPOSE, VIEWS_RUNTIME_SCREEN, viewsFiles } from "./features/views.ts";
+import { packageReleaseSh, SERVER_KIT_GITIGNORE, shipImageSh } from "./server-kit.ts";
 
 // The per-feature section of the generated CLAUDE.md: what each optional
 // workspace is, and the trap that comes with it. Every line here is something
@@ -182,6 +183,15 @@ container port 4321), then \`bun run demo -- up --mode image --daemon reuse\`:
 the driver deletes the instance, removes the template + product, re-adds the
 fresh image and checks the pins before relaunching.
 
+**A customer's server:** \`bun run package-release\` writes \`release/\`: the
+image as a tar (tagged by commit, so a server tells releases apart), the
+drift-gated \`deployment/install.sh\` and \`deployment/uninstall.sh\`, and
+\`release.env\`. Copied to the server, \`install.sh --license <file>\` takes a
+bare box to a running instance and upgrades one in place (norsk-ctl too,
+media kept); every template parameter is taken from a same-named environment
+variable. \`uninstall.sh\` restores the box and lists anything left. A dev box
+with no registry access: \`bun run ship-image -- <ssh-host>\`.
+
 ## First run after generation
 
 1. \`nix develop\` — the dev shell: pinned bun, biome and norsk-ctl.
@@ -359,6 +369,8 @@ function rootPackageJson(ctx: ShapeContext): string {
         ...(hasFrontend ? { "dev:frontend": "bun run --cwd frontend dev" } : {}),
         start: "bun run --cwd backend start",
         iterate: "bash deployment/iterate.sh",
+        "package-release": "bash deployment/package-release.sh",
+        "ship-image": "bash deployment/ship-image.sh",
         demo: "ctl-demo",
       },
       devDependencies: {
@@ -1936,6 +1948,7 @@ shared/dist
 .git
 .github
 *.md
+release
 `;
 
 function exampleInputJson(_ctx: ShapeContext): string {
@@ -2240,6 +2253,7 @@ function gitignoreTail(ctx: ShapeContext): string {
   if (ctx.features.has("components")) blocks.push(COMPONENTS_GITIGNORE);
   if (ctx.features.has("dashboard")) blocks.push(DASHBOARD_GITIGNORE);
   blocks.push(DOCS_SITE_GITIGNORE);
+  blocks.push(SERVER_KIT_GITIGNORE);
   return blocks.join("\n");
 }
 
@@ -2259,6 +2273,10 @@ export const turnkey: ShapeModule = {
       { path: ".dockerignore", content: DOCKERIGNORE },
       { path: "examples/default/input.json", content: exampleInputJson(ctx) },
       { path: "deployment/iterate.sh", content: iterateSh(ctx), executable: true },
+      { path: "deployment/package-release.sh", content: packageReleaseSh(ctx), executable: true },
+      { path: "deployment/ship-image.sh", content: shipImageSh(ctx), executable: true },
+      { path: "deployment/install.sh", content: ctx.canon.serverInstall, executable: true },
+      { path: "deployment/uninstall.sh", content: ctx.canon.serverUninstall, executable: true },
       { path: "scripts/demo", content: ctx.canon.demoShim, executable: true },
       { path: "README.md", content: readmeMd(ctx) },
       ...docsSiteFiles(ctx),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.2.75",
+  "version": "0.2.76",
   "type": "module",
   "exports": {
     "./create-product": "./create-product/create-product.ts",