@norskvideo/ctl-dev-kit 0.2.77 → 0.2.78

package/create-product/turnkey.ts

@@ -328,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
@@ -2044,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\`
@@ -2070,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                          |
 
@@ -2113,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
@@ -2218,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
@@ -2298,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.77",
+  "version": "0.2.78",
   "type": "module",
   "exports": {
     "./create-product": "./create-product/create-product.ts",