@norskvideo/ctl-dev-kit 0.2.76 → 0.2.78

package/create-product/turnkey.ts

@@ -170,11 +170,16 @@ pinned in \`flake.nix\` and put on PATH by the nix shell:
 \`norsk-ctl product add --dev-url http://localhost:${ctx.devPort}\` registers the
 running backend as a dev product.
 
+**Licence:** commit a non-production dev licence for this product at
+licensing/${ctx.name}-dev.json and \`bun run iterate\` uses it whenever
+\`NORSK_LICENSE_FILE\` is unset; export it yourself for \`bun run demo\`.
+
 **Demo:** \`bun run demo -- up\` runs \`tests/demo.spec.ts\` (the
 @norskvideo/ctl-test-harness demo driver) from source on a private daemon —
 dev backend, registration, launch, the camera1 sample on the ingest, ready
 gates, URLs; Ctrl-C tears down. \`check\` is the headless form CI runs,
-\`spec\` prints the plan. \`scripts/demo\` is the same entry re-exec'd under
+\`spec\` prints the plan. \`DEMO_SOURCES=none\` skips the sample, for feeds
+pushed in by hand. \`scripts/demo\` is the same entry re-exec'd under
 \`nix develop .#dev\` when the pinned ctl is not on PATH.
 
 **Outer loop (real image):** \`bun run iterate\` — \`bun run build:image\` (the
@@ -323,7 +328,7 @@ function rootPackageJson(ctx: ShapeContext): string {
         "check:drift": "bun run node_modules/@norskvideo/ctl-dev-kit/conventions/check-drift.ts",
         "docs:check":
           "bun run node_modules/@norskvideo/ctl-dev-kit/docs/path-existence.ts && bun run node_modules/@norskvideo/ctl-dev-kit/docs/light-pages.ts && bun run node_modules/@norskvideo/ctl-dev-kit/docs/journeys.ts",
-        "docs:manual": `bun run node_modules/@norskvideo/ctl-dev-kit/doc-guide/prose-bundle.js --brand "${ctx.name}" --title "${ctx.name} — Documentation" --link "norsk.video=https://norsk.video/" --out docs/generated/bundle docs/handover.md docs/operating.md docs/known-limitations.md`,
+        "docs:manual": `bun run node_modules/@norskvideo/ctl-dev-kit/doc-guide/prose-bundle.js --brand "${ctx.name}" --title "${ctx.name} — Documentation" --link "norsk.video=https://norsk.video/" --out docs/generated/bundle docs/handover.md docs/administering.md docs/operating.md docs/known-limitations.md`,
         "docs:handover": "bash scripts/docs-handover.sh",
         "docs:handover:check": "bash scripts/docs-handover.sh --check",
         // The docs SITE (website/) — a standalone package, so its install is its
@@ -1817,7 +1822,8 @@ function iterateSh(ctx: ShapeContext): string {
 # instance; your daemon and the registration stay.
 #
 # Needs the daemon already running (\`norsk-ctl serve\`), \`norsk-ctl\` on PATH
-# (\`nix develop .#dev\` provides it) and NORSK_LICENSE_FILE.
+# (\`nix develop .#dev\` provides it) and a licence: NORSK_LICENSE_FILE, else
+# the committed non-production dev licence at licensing/${ctx.name}-dev.json.
 #
 # Usage (from the repo root):
 #   bun run iterate                     # full loop
@@ -1832,6 +1838,10 @@ repo="$(cd "$here/.." && pwd)"
 # directly (build-image.sh honours IMAGE_TAG).
 export IMAGE_TAG="\${IMAGE_TAG:-${ctx.name}:dev}"
 
+if [ -z "\${NORSK_LICENSE_FILE:-}" ] && [ -f "$repo/licensing/${ctx.name}-dev.json" ]; then
+  export NORSK_LICENSE_FILE="$repo/licensing/${ctx.name}-dev.json"
+fi
+
 if [ -n "\${SKIP_BUILD:-}" ]; then
   echo "=== build (skipped, SKIP_BUILD set) ==="
 else
@@ -1908,7 +1918,12 @@ export default defineDemo({
   image: process.env.IMAGE_TAG ?? "${ctx.name}:dev",
   template: { name: "default" },
   launch: { hardware: "none" },
-  sources: [{ name: "input", asset: { preset: "camera1" }, ingest: { param: "INGEST_PORT" }, streamId: "input" }],
+  // DEMO_SOURCES=none leaves the ingest to feeds someone pushes in by hand
+  // (stream id input), so they can be stopped and started live.
+  sources:
+    process.env.DEMO_SOURCES === "none"
+      ? []
+      : [{ name: "input", asset: { preset: "camera1" }, ingest: { param: "INGEST_PORT" }, streamId: "input" }],
   ready: [{ http: { studio: "/live/api/components" }, status: 200, timeoutMs: 120_000 }],
   open: [
     { name: "Studio", url: { proxy: "/instance/{id}/studio/" } },
@@ -2029,7 +2044,8 @@ norsk-ctl and the pinned Norsk SDK:
 Two channels, deliberately:
 
 - **The bundle the image serves.** \`bun run docs:manual\` builds it from
-  \`docs/handover.md\`, \`docs/operating.md\` and \`docs/known-limitations.md\`;
+  \`docs/handover.md\`, \`docs/administering.md\`, \`docs/operating.md\` and
+  \`docs/known-limitations.md\`;
   the image build runs
   it, so every image serves them at /docs at the version that is running
   (linked from the product's page in norsk-ctl). \`bun run docs:handover\`
@@ -2055,6 +2071,7 @@ served at /docs at the version that is running.
 | Document                     | Audience                                  | What it is                                                                                          |
 | ---------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------- |
 | \`docs/handover.md\`          | whoever gets this product running         | How norsk-ctl arrives, the one command that adds this product, and the bundle route for platform teams |
+| \`docs/administering.md\`     | the server's administrator                | What runs on the server and where, how to reach it, update it, back it up and remove it            |
 | \`docs/operating.md\`         | operators                                 | What a running deployment looks like from the operator's chair: the controls, the checks, the signs |
 | \`docs/known-limitations.md\` | operators                                 | What the product does not do yet, with the consequence and the workaround                          |
 
@@ -2098,7 +2115,7 @@ the Administrator's hat._
 | Evaluator     | \`/docs/\`           | \`/docs/guides/\`                        | [norsk-ctl's manual](https://ctl.norsk.video/), to run it for real      |
 | Builder       | \`/docs/guides/\`    | \`/docs/how-to/\`                        | \`/docs/reference/\`, for the settings they just used                    |
 | Integrator    | \`/docs/reference/\` | \`/docs/concepts/\`                      | [norsk-ctl's CLI and API reference](https://ctl.norsk.video/)           |
-| Administrator | \`handover.md\`      | \`operating.md\`, \`known-limitations.md\` | [norsk-ctl's manual](https://ctl.norsk.video/), for everything about the machine |
+| Administrator | \`handover.md\`      | \`administering.md\`, \`operating.md\`, \`known-limitations.md\` | [norsk-ctl's manual](https://ctl.norsk.video/), for everything about the machine |
 
 Site paths resolve under website/src/content/docs; a bare name resolves under
 docs/. Each route is at most five pages and ends in a hand-off, which is the
@@ -2203,6 +2220,122 @@ and its health check at /healthz are for._
 `;
 }
 
+// The server admin's page: the product running under norsk-ctl on the
+// customer's own machine (gameplay-football247's dev-ops guide, generalised).
+// norsk-ctl's server install is the same everywhere, so its half is written
+// out; the product's half carries a marker per section.
+function administeringMd(ctx: ShapeContext): string {
+  return `# Administering ${ctx.name}
+
+For whoever looks after the server ${ctx.name} runs on: what is installed
+where, how to reach it, how to update it, and how to remove it. Getting it
+running the first time is in handover.md; running the product day to day is in
+operating.md.
+
+## What runs on the server
+
+${ctx.name} runs under **norsk-ctl**, Norsk's service manager.
+
+| Process / container | What it is |
+|---|---|
+| \`norsk-ctl\` (systemd service) | The manager: launches and supervises ${ctx.name}, serves its API |
+| \`norsk-proxy\`, \`norsk-proxy-oauth2\` | The HTTPS entry point and its login |
+| \`norsk-product-${ctx.name}\` | The product's control plane |
+| \`<instance>-<service>-1\` | One per service of a launched instance |
+
+<!-- ctl-docs-template: fill me -->
+_Name this product's instance containers and say what each one does (the
+starter's are Studio, the workflow and its dashboard, and the media engine)._
+
+## Where things are
+
+| Path | Contents |
+|---|---|
+| \`/etc/norsk-ctl/\` | norsk-ctl's configuration (\`config.yaml\`), licences, TLS certificate |
+| \`/var/lib/norsk-ctl/\` | norsk-ctl's state: database, product registry, templates, proxy |
+| \`/var/log/norsk-ctl/\` | norsk-ctl's logs |
+| \`/opt/norsk-ctl/bin/\` | norsk-ctl binaries, one per version; \`/usr/local/bin/norsk-ctl\` points at the current one |
+| \`/etc/systemd/system/norsk-ctl.service\` | The service unit |
+| \`/etc/sysctl.d/90-norsk-tuning.conf\` | Network buffer tuning for media |
+<!-- path-allow -->
+
+<!-- ctl-docs-template: fill me -->
+_Add the instance's working directory (uploaded media, settings) and anything
+else this product keeps on disk._
+
+norsk-ctl runs as the user \`norsk\`. Run its CLI as that user, with its
+configuration:
+
+\`\`\`sh
+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 instance list
+\`\`\`
+
+## Network
+
+<!-- ctl-docs-template: fill me -->
+| Port | Open to | What |
+|---|---|---|
+| 22/tcp | administrators | SSH |
+| _443/tcp_ | _operators_ | _The web page (or loopback only: see below)_ |
+| _the product's inputs and outputs_ | _the senders and receivers_ | _one row per media port_ |
+
+## Reaching the web page
+
+The web page is norsk-ctl's proxy. On a server that must not expose it, bind it
+to loopback (norsk-ctl's \`bindAddress\` setting) and reach it through an SSH
+tunnel:
+
+\`\`\`sh
+ssh -L 8443:127.0.0.1:443 <you>@<server>   # 443: the proxy's port, if unchanged
+# then browse https://localhost:8443
+\`\`\`
+
+A self-signed certificate is accepted once in the browser.
+
+## Installing and updating
+
+<!-- ctl-docs-template: fill me -->
+_The release this product ships and the one command that installs or updates
+it, with the settings it takes. Without a release kit: norsk-ctl's installer,
+then \`norsk-ctl product add\` (handover.md); a new image is \`norsk-ctl product
+reload\`; norsk-ctl itself is \`norsk-ctl upgrade --version <v>\`, as root._
+
+## Checking it is healthy
+
+\`\`\`sh
+systemctl status norsk-ctl     # the manager
+journalctl -u norsk-ctl -f     # its log
+docker ps                      # every container above, Up
+\`\`\`
+
+<!-- ctl-docs-template: fill me -->
+_What the product's own page shows when it is healthy, and which container's
+log to read first when it is not._
+
+## Removing it
+
+<!-- ctl-docs-template: fill me -->
+_How to remove the product, and norsk-ctl with it, and what is left behind.
+Say plainly what is deleted (uploaded media) and how to keep it._
+
+## Backups
+
+norsk-ctl's state worth keeping is \`/etc/norsk-ctl\` and \`/var/lib/norsk-ctl\`,
+plus each instance's working directory.
+
+<!-- ctl-docs-template: fill me -->
+_Anything else of this product's that is worth keeping._
+
+## Licence
+
+${ctx.name} runs under a Norsk licence that entitles it, staged in
+\`/etc/norsk-ctl/licenses/\`. The product takes its licence when it is added
+(\`norsk-ctl product add --license-file\`), so a new licence goes in with the
+next \`product add\`.
+`;
+}
+
 const KNOWN_LIMITATIONS_MD = `# Known limitations
 
 What this product does not do yet, or does with a caveat an operator must know
@@ -2283,6 +2416,7 @@ export const turnkey: ShapeModule = {
       { path: "docs/README.md", content: docsReadmeMd(ctx) },
       { path: "docs/handover.md", content: handoverMd(ctx) },
       { path: "docs/operating.md", content: operatingMd(ctx) },
+      { path: "docs/administering.md", content: administeringMd(ctx) },
       { path: "docs/known-limitations.md", content: KNOWN_LIMITATIONS_MD },
       { path: "docs/personas.md", content: personasMd(ctx) },
       { path: ".github/workflows/build-docs.yml", content: ctx.canon.buildDocs },

package/package.json

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