diff --git a/docs/docs.json b/docs/docs.json index 761b6b94..0762a00b 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -95,22 +95,28 @@ "pages": [ "features/overview", { - "group": "Stacks & Deployments", + "group": "Stacks", "pages": [ "features/stack-management", - "features/stack-activity", "features/editor", "features/stack-file-explorer", - "features/deploy-progress", - "features/resources", - "features/app-store", - "features/atomic-deployments", - "features/deploy-enforcement", - "features/blueprint-model", - "features/git-sources", - "features/stack-labels" + "features/stack-activity", + "features/stack-labels", + "features/sidebar" ] }, + { + "group": "Deployment", + "pages": [ + "features/deploy-progress", + "features/atomic-deployments", + "features/deploy-enforcement", + "features/git-sources", + "features/app-store", + "features/blueprint-model" + ] + }, + "features/resources", { "group": "Observability", "pages": [ @@ -122,7 +128,7 @@ ] }, { - "group": "Fleet & Multi-Node", + "group": "Fleet", "pages": [ "features/multi-node", "features/pilot-agent", @@ -134,7 +140,17 @@ "features/fleet-secrets", "features/fleet-backups", "features/remote-updates", - "features/scheduled-operations" + "features/node-compatibility", + "features/host-console" + ] + }, + { + "group": "Automation", + "pages": [ + "features/scheduled-operations", + "features/auto-update-policies", + "features/auto-heal-policies", + "features/webhooks" ] }, { @@ -148,34 +164,9 @@ "features/cve-suppressions", "features/private-registries" ] - }, - { - "group": "Automation", - "pages": [ - "features/auto-update-policies", - "features/auto-heal-policies", - "features/webhooks" - ] - }, - { - "group": "Platform", - "pages": [ - "features/sidebar", - "features/host-console" - ] } ] }, - { - "group": "Reference", - "pages": [ - "reference/settings", - "features/licensing", - "features/node-compatibility", - "security", - "reference/contact" - ] - }, { "group": "Operations", "pages": [ @@ -187,6 +178,15 @@ "operations/trivy-setup", "operations/two-factor-admin" ] + }, + { + "group": "Reference", + "pages": [ + "reference/settings", + "features/licensing", + "reference/security", + "reference/contact" + ] } ] }, diff --git a/docs/features/app-store.mdx b/docs/features/app-store.mdx index 990cc752..2558bc9a 100644 --- a/docs/features/app-store.mdx +++ b/docs/features/app-store.mdx @@ -117,7 +117,7 @@ Clicking **Deploy** runs the following sequence: ## Watching the deploy -Sencho can stream the live `docker compose` output for every template install. Open **Settings › Appearance › Display** and enable **Deploy progress modal**; from then on, every App Store deploy opens a structured log modal you can minimise to a pill that follows you across navigation. See [Deploy Progress Modal](/features/deploy-progress) for the full reference. +Sencho can stream the live `docker compose` output for every template install. Open **Settings › Appearance › Display** and enable **Deploy progress modal**; from then on, every App Store deploy opens a structured log modal you can minimise to a pill that follows you across navigation. See [Deploy Progress](/features/deploy-progress) for the full reference. Deploying a template requires the `stack:create` permission on the target node, which **admin** and **node-admin** roles hold by default. The Deploy button stays disabled when your account does not have it. diff --git a/docs/features/auto-update-policies.mdx b/docs/features/auto-update-policies.mdx index 38695870..f32bcbb6 100644 --- a/docs/features/auto-update-policies.mdx +++ b/docs/features/auto-update-policies.mdx @@ -1,10 +1,10 @@ --- -title: "Auto-Update Readiness" +title: "Auto-Update Policies" description: "Review pending container updates across your fleet, with risk badges, changelogs, and scheduled run times, before applying." --- - Auto-Update Readiness requires a **Skipper** or **Admiral** license. + Auto-Update Policies require a **Skipper** or **Admiral** license. @@ -13,7 +13,7 @@ description: "Review pending container updates across your fleet, with risk badg ## Overview -Auto-Update Readiness is the launchpad for every pending update across your stacks. Instead of a list of CRUD policies, the view surfaces one card per stack with an available update and tells you, at a glance, whether it is safe to apply. +Auto-Update Policies are the launchpad for every pending update across your stacks. Instead of a list of CRUD policies, the view surfaces one card per stack with an available update and tells you, at a glance, whether it is safe to apply. Each card shows: diff --git a/docs/features/deploy-progress.mdx b/docs/features/deploy-progress.mdx index 22c3c067..7e911488 100644 --- a/docs/features/deploy-progress.mdx +++ b/docs/features/deploy-progress.mdx @@ -1,5 +1,5 @@ --- -title: Deploy Progress Modal +title: Deploy Progress description: Stream live output from stack deploy, install, update, restart, and stop operations in a structured log view. --- diff --git a/docs/features/node-compatibility.mdx b/docs/features/node-compatibility.mdx index 05ea78a5..685b032a 100644 --- a/docs/features/node-compatibility.mdx +++ b/docs/features/node-compatibility.mdx @@ -60,7 +60,7 @@ Every Sencho release ships with a static list of capabilities. The current list | `global-logs` | Global log viewer (always available) | | `system-stats` | Host system statistics (always available) | | `fleet` | Fleet management view | -| `auto-updates` | Auto-Update Readiness policies | +| `auto-updates` | Auto-Update policies | | `labels` | Stack labels | | `webhooks` | Webhook triggers | | `network-topology` | Network topology view | diff --git a/docs/features/overview.mdx b/docs/features/overview.mdx index 017aae50..b725ae8a 100644 --- a/docs/features/overview.mdx +++ b/docs/features/overview.mdx @@ -171,7 +171,7 @@ Store credentials for private Docker registries: Docker Hub organizations, GHCR, ## Automation -### Auto-Update Readiness +### Auto-Update Policies Review pending container updates across your fleet with risk badges (`Safe · patch`, `Review · minor`, `Blocked · major`, `Digest rebuild`) and one-line changelog previews on a single board. The hero counts pending updates and tells you how many are ready to apply without human review; stacks with a major version bump are surfaced as a separate count for review. Skipper or Admiral. [Learn more →](/features/auto-update-policies) diff --git a/docs/features/pilot-agent.mdx b/docs/features/pilot-agent.mdx index 048ee087..a3516ae4 100644 --- a/docs/features/pilot-agent.mdx +++ b/docs/features/pilot-agent.mdx @@ -359,4 +359,4 @@ The generic node-connectivity issues (a node showing Offline, a pilot agent stuc - [Multi-Node Management](/features/multi-node): the operator walkthrough for adding remote nodes in either mode, the Nodes table reference, and the cross-mode comparison. - [Sencho Mesh](/features/sencho-mesh): cross-node networking that rides on the pilot tunnel. - [Fleet view](/features/fleet-view): fleet-wide aggregation and node health across both modes. -- [Security architecture](/security): credential model and trust posture across the rest of Sencho. +- [Security architecture](/reference/security): credential model and trust posture across the rest of Sencho. diff --git a/docs/features/scheduled-operations.mdx b/docs/features/scheduled-operations.mdx index b611b832..87a2583b 100644 --- a/docs/features/scheduled-operations.mdx +++ b/docs/features/scheduled-operations.mdx @@ -59,7 +59,7 @@ The All tasks toggle swaps the lane track for a sortable table. | Action | Target | What it does | |---|---|---| | **Restart Stack** | A specific stack (optionally specific services) on a specific node | Restarts all or selected containers in the stack. | -| **Auto-update Stack** | A specific stack on a specific node | Checks each image in the stack for a newer tag and recreates the stack if any image has an update. See [Auto-Update Readiness](/features/auto-update-policies) for the companion review board. | +| **Auto-update Stack** | A specific stack on a specific node | Checks each image in the stack for a newer tag and recreates the stack if any image has an update. See [Auto-Update Policies](/features/auto-update-policies) for the companion review board. | | **Auto-update All Stacks** | A specific node | Runs the auto-update check across every stack on the node that has auto-updates enabled. Stacks with auto-updates turned off are skipped. | | **Fleet Snapshot** | The whole fleet | Creates a versioned, fleet-wide snapshot of every node's compose files and `.env` files. See [Fleet Backups](/features/fleet-backups). | | **System Prune** | The selected node | Prunes containers, images, networks, and volumes (any subset), optionally filtered by a Docker label. | diff --git a/docs/operations/verifying-images.mdx b/docs/operations/verifying-images.mdx index 41fcfaa0..21d6e12f 100644 --- a/docs/operations/verifying-images.mdx +++ b/docs/operations/verifying-images.mdx @@ -111,3 +111,15 @@ A clean result means no unresolved HIGH or CRITICAL CVEs. CVEs listed as `not_af Trivy 0.36.0 or later is required for `--vex` flag support. + +## Available tags + +Each release publishes two moving tags plus one immutable tag, so you can choose how aggressively you want to track updates: + +| Tag | Example | Updates on | +|---|---|---| +| `latest` | `saelix/sencho:latest` | Every release | +| `X.Y` | `saelix/sencho:0.42` | Every patch release in the `0.42.x` line | +| `X.Y.Z` | `saelix/sencho:0.42.7` | Never (immutable) | + +For production, pin to `X.Y.Z` or `X.Y` and verify the signature on every pull. For staging or development, `latest` is fine. diff --git a/docs/security.mdx b/docs/reference/security.mdx similarity index 100% rename from docs/security.mdx rename to docs/reference/security.mdx diff --git a/docs/reference/verifying-images.mdx b/docs/reference/verifying-images.mdx deleted file mode 100644 index e55c2678..00000000 --- a/docs/reference/verifying-images.mdx +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Verifying Docker Images -description: Verify that the Sencho image you pulled was built and signed by the official GitHub Actions pipeline. ---- - -Every published Sencho Docker image is signed by the official GitHub Actions pipeline using [Sigstore cosign](https://docs.sigstore.dev/) keyless signing. The signature is backed by a short-lived certificate issued by Sigstore's public Fulcio certificate authority, tied to the GitHub Actions workflow run that produced the image. You can verify this signature yourself before pulling the image into production. - -Every image also ships with an embedded SBOM (Software Bill of Materials) and [SLSA](https://slsa.dev) (Supply-chain Levels for Software Artifacts) provenance attestation, so you can inspect exactly what went into the image and which workflow run built it. - - - Image signing is available starting with Sencho **v0.43.0**. Earlier releases do not ship a cosign signature; running `cosign verify` against them will fail, which is expected and does not indicate tampering. If you are on an older version, the first step is to upgrade. - - -## Why verify - -Verification guarantees: - -1. The image was built from the [studio-saelix/sencho](https://github.com/studio-saelix/sencho) repository on GitHub. -2. The build ran inside a GitHub Actions workflow, not on someone's laptop. -3. The image has not been tampered with between publish and pull. - - - Verification is optional. If you skip it, Sencho still works exactly the same; you are just trusting Docker Hub to deliver the right bytes. Verification adds a second independent check. - - -## Install cosign - -[cosign](https://docs.sigstore.dev/system_config/installation/) is a single static binary. Install it once on any machine you use to pull Sencho. - - - -```bash macOS (Homebrew) -brew install cosign -``` - -```bash Linux (binary) -curl -Lo cosign https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64 -chmod +x cosign -sudo mv cosign /usr/local/bin/ -``` - -```bash Windows (Scoop) -scoop install cosign -``` - - - -## Verify a released image - -Replace `` with the version you intend to pull, for example `0.42.7`, `0.42`, or `latest`. - -```bash -cosign verify saelix/sencho: \ - --certificate-identity-regexp "https://github.com/studio-saelix/sencho/.*" \ - --certificate-oidc-issuer https://token.actions.githubusercontent.com -``` - - - Images released before the repository migration (prior to v0.65.x) were signed with the identity `https://github.com/AnsoCode/Sencho/...`. To verify those older images, use the combined regexp: - `"https://github.com/(AnsoCode/Sencho|studio-saelix/sencho)/.*"` - - -A successful verification prints the signature, the Rekor transparency log entry, and the certificate that signed it. If the image is not signed by the official Sencho pipeline, the command exits with a non-zero status and you should not run that image. - -## Inspect the SBOM and provenance - -Both the SBOM and SLSA provenance are attached to the published image as [OCI referrers](https://docs.docker.com/build/attestations/attestation-storage/). You can inspect them with `docker buildx imagetools`: - -```bash -docker buildx imagetools inspect saelix/sencho: --format "{{json .SBOM}}" -docker buildx imagetools inspect saelix/sencho: --format "{{json .Provenance}}" -``` - -The SBOM lists every package baked into the image with versions and licenses. The provenance records the exact GitHub Actions workflow run, commit SHA, and builder that produced it. - -## Available tags - -Each release publishes two moving tags plus one immutable tag, so you can choose how aggressively you want to track updates: - -| Tag | Example | Updates on | -|---|---|---| -| `latest` | `saelix/sencho:latest` | Every release | -| `X.Y` | `saelix/sencho:0.42` | Every patch release in the `0.42.x` line | -| `X.Y.Z` | `saelix/sencho:0.42.7` | Never (immutable) | - -For production, pin to `X.Y.Z` or `X.Y` and verify the signature on every pull. For staging or development, `latest` is fine.