mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-08-18 14:33:19 +00:00
docs: v1 docs refresh (batch 7) (#1627)
* docs(introduction): refresh screenshots and correct stale nav/tab coverage
Replace all 5 screenshots with fresh 1920x1080 production captures.
Document the shipped Take down stack action, the Compose Labels stack
tab, and the Docker Labels Fleet tab, none of which were mentioned.
Correct the Console nav item to note it is a limited-availability
surface rather than a plain role/tier-gated view.
* docs(quickstart): refresh screenshots and correct preflight, dashboard, and menu drift
Replace all three quickstart screenshots with fresh captures and correct
several claims that drifted from the current UI:
- Document the environment preflight's 7th check (Sencho compose
location), previously missing entirely from both the text and the
screenshot alt text.
- Add the Stack health table's Source and Port columns, and note that
columns are sortable and default to load order.
- Note the masthead's running-container count, live CPU/memory readout,
and alert count.
- Fix the profile menu list: replace the nonexistent "Feedback" entry
with "Open New Issue", drop "Appearance" (it lives in Settings, not
the profile menu), and add the conditional "Billing" entry.
- Note that the sidebar groups stacks by Docker Compose label once
labels are assigned, with pinned stacks first.
* docs(configuration): document missing env vars and fix JWT secret wording
Add SENCHO_UPLOAD_DIR, TRIVY_CACHE_DIR, SENCHO_MESH_RECONCILE_INTERVAL_MS,
SENCHO_MESH_PROXY_TUNNEL_IDLE_MS, SENCHO_COMPOSE_COMMAND_TIMEOUT_MS, and
SSO_OIDC_CUSTOM_ENABLED, all real environment variables that were missing
from the reference tables. Clarify that the JWT signing secret has no
environment variable at all, generated and stored in the database only,
rather than implying an unused JWT_SECRET var exists.
* docs(stack-management): refresh against current live app and source
Rewrites the Stack Management page against the production node and
frontend source: adds the Compose Labels anatomy tab (new since the
last refresh), the Mute action on the stack header and sidebar
context menu, corrects the update-available banner wording and the
sidebar context menu's lifecycle ordering, notes the Doctor tab's
severity dot and the scan-status banner, and replaces all 14
screenshots with fresh production captures.
* docs(editor): refresh against current live app and source
Replace all 8 screenshots with fresh 1920x1080 production captures (mobile
shot at phone viewport). Document the self-stack protection dialog that
blocks deploy/delete actions on the stack running the current Sencho
instance, the multi-container summary strip and Compact/Detailed density
toggle, the mutually exclusive Expand containers / Expand logs controls,
the Files tab full-screen toggle, and the post-deploy scan-status banner
on the Anatomy panel, none of which were previously covered.
* docs(editor): recapture mobile compose screenshot without redaction
The previous mobile screenshot used the plex stack, whose compose volume
mount includes a real host path that had to be blacked out and overlaid
with placeholder text, leaving a visible seam. Recapture against the
dozzle stack instead, whose only volume is the Docker socket, so the
screenshot needs no editing.
* docs(stack-file-explorer): refresh page against current app and code
Renames "Files & Volumes tab" references to the current "Files" tab
label, documents the full-screen toggle and word-wrap control, expands
the non-browsable-volume reasons to match the current containment
logic (single-file binds, the full protected host-path list, and the
Docker-unreachable named-volume case), documents the 100-item bulk
selection cap and the 5000-file/1 GiB archive limits, corrects the
non-existent DISK_FULL error code, notes that override compose files
are unprotected, and scopes the atomic-write claim to fs-backed roots.
Replaces all 9 screenshots with fresh production captures taken in the
Files tab's full-screen mode, so no other stack UI (health metrics,
logs) appears in the background.
* docs(resources): refresh against current live app and source
* docs(dashboard): refresh against current live app and source
* docs(app-store): refresh against current live app and source
Replaces all 6 screenshots with fresh production captures and corrects
the Environment Variables and About-panel metadata claims to match what
the bundled LinuxServer.io registry actually returns today.
* fix(docs): recapture app-store advanced-tab screenshot without scroll cut-off
The prior capture was taken mid-scroll to reveal the Security checkbox,
leaving the template logo and About text cropped awkwardly at the top.
* docs(global-search): refresh against current live app and source
* docs(deep-links): refresh against current live app and source
- Add App Store, Logs, Update, Console, and Audit to the URL table (previously undocumented)
- Document hub-only URL redirect behavior and cross-link to Multi-Node Fleet
- Note Fleet tab URL segments do not always match their on-screen label (Status/configuration, Map/dependencies)
- Document the no-env-files edge case (Env tab absent, falls back to compose)
- Clarify Settings section-list state is phone-only; desktop always normalizes to /settings/appearance
- Note which top-level views share identical URLs between desktop and phone
- Remove greenfield-violating temporal phrasing ("now has", "as today")
- Replace em dashes in touched bullet list
* docs(appearance): refresh against current live app and source
* docs(stack-activity): refresh against current live app and source
Add the missing "Stack taken down" event category, cross-link the
Suppressed badge to notification mute rules, list the new Compose
Labels tab in the Anatomy panel strip, and replace both screenshots
with current production captures.
* docs(dossier): fix generated-facts wording, add rollback readiness section
Corrects three Dossier tab Generated Facts rows against current frontend
behavior: the Ports count is not filtered to host-published mappings, the
Network row's "bridge" label is fixed text rather than a derived driver,
and missing env var names appear only in the Markdown export, not the
live tab. Adds a Rollback Readiness subsection under Connected Features
(previously only an orphaned Limitations bullet), links to Compose
Networking and Storage Portability, and clarifies that a missing export
section can mean either an older node build or a failed on-demand fetch,
not only a version gap. Recaptures all three screenshots against
production.
* docs(stack-drift): refresh against current live app and source
Fixes the stack detail tab bar description (Compose Labels tab was
missing, Files/Edit compose were wrongly listed as tabs), documents
that re-check only requires read access to the stack (so viewer and
auditor roles can trigger a ledger write), and cross-links the network
findings to the Networking tab's runtime drift section and the Fleet
Overview's Drift filter. Replaces all four screenshots with fresh
1920x1080 production captures.
* docs(compose-doctor): refresh against current live app and source
Corrects the rule count from 31 to 32 and documents the previously
undocumented self-managed-stack guard rule and enforcement, the
per-browser dismiss control for the summary card and Doctor tab dot,
the acknowledged summary state, the full Health-Gated Updates verdict
mapping, and the temporary exposure intent option. Replaces all four
screenshots with production captures.
* docs(compose-networking): refresh against current live app and source
Adds cross-links to the new node-wide Networking operator page, documents
the "view node networking" link and the unset/inherit exposure-intent pill
labels, corrects the stale Resources Hub network-tab reference, and
replaces all screenshots against the production node.
* fix(docs): unbreak stack-activity page render
The screenshot alt text used backslash-escaped quotes, which is
invalid MDX/HTML attribute syntax. Mintlify failed to parse the file
and silently dropped it from routing, so the page 404'd despite being
listed in docs.json navigation.
* docs(environment-guardrails): refresh against current live app and source
Fix the ENV FILES section description: it lists env_file: entries and
project files with an existence problem, not every declared env file.
A cleanly-resolving project file is already named in the Project
Environment File panel above it. Replace all three screenshots with
current production captures.
* docs(docker-label-audit): refresh against current live app and source
Add production screenshots (page had none), a Capability gating
section, a Limitations section, and a Troubleshooting accordion.
Tighten the secret-redaction heuristic description and cross-link
Stack Labels, Compose Doctor, Environment Guardrails, and Node
Compatibility.
* docs(compose-storage): refresh against current live app and source
Captured fresh production screenshots (both prior images were stale)
and fixed a leftover pre-rename card title pointing at the Files tab.
* docs(stack-labels): refresh against current live app and source
Removed the stale trailing-dot sidebar claim (that rendering was
removed from the sidebar in a prior UI pass), documented the new
label-scoped notification muting available from the sidebar, stack
context menu, and Settings panel, corrected the Fleet Actions card
copy to match the redesigned cards, added the previously undocumented
bulk-assign size cap and the node-scoped label bulk-action API, and
replaced all 8 screenshots with fresh production captures.
* docs(sidebar): refresh against current live app and source
Removes the stale per-row label dot claim (removed from StackRow), corrects the update indicator and Updates chip color from orange to fuchsia, and documents Mute/Take down in the context menu, the label group mute kebab, Ctrl+A/Esc bulk-mode shortcuts, pin-eviction toast, and the offline-node skip behavior in cross-node search. Replaces all 8 screenshots with fresh production captures.
* docs(deploy-progress): refresh against current live app and source
Corrected the Scan entry point (node-wide Scan this node from Security
Overview, not a per-stack config scan), added the missing Take down
verb and entry point, broadened recovery actions to cover restart and
rollback failures, fixed the modal status text and raw-output color
claims to match the live UI, and replaced all screenshots with fresh
captures from a throwaway demo stack on the production node.
* docs(atomic-deployments): refresh against current live app and source
* docs(health-gated-updates): refresh against current live app and source
* docs(deploy-enforcement): refresh against current live app and source
Correct the tier note to every-tier (verified against the current
policy gate, which no longer has a paid-only blocking switch), add the
Security Overview deploy-enforcement summary card, tighten the honor-
suppressions default wording, cross-link the separate pre-deploy scan
advisory dialog to avoid confusion with the block dialog, and replace
all three screenshots against the current production UI.
* docs(blueprint-model): refresh against current live app and source
Replaced all 11 screenshots with fresh production captures. Corrected
the volume-destroying-drift Enforce-downgrade claim (appeared three
times): that code path has no call sites in the runtime reconciler, so
any compose edit on a stateful or state-unknown blueprint always
re-enters Awaiting confirmation regardless of drift mode. Corrected
the Create workflow (creation does not trigger an immediate
reconciliation tick) and the Delete workflow (now requires typing the
blueprint name to confirm).
* docs(scheduled-operations): refresh against current live app and source
* docs(blueprint-model): drop tier framing, treat as Community-native
Blueprints carry no tier gate, so "available on every tier" implied a
comparison that doesn't exist. Removed the tier framing from the intro
note, the Prerequisites table, and the Security section; the role
requirement (admin to write, every role to read) already says
everything that matters.
* docs(auto-update-policies): refresh against current live app and source
Documents that every update trigger on this page, Apply now and
scheduled Auto-update tasks alike, runs through the same atomic backup,
build-aware rebuild, and post-update health gate as a manual update
from the stack editor, and is subject to the same deploy enforcement
policy gate. Corrects the readiness-computation description to scope it
to registry-image services and cross-links to Health-Gated Updates,
Atomic Deployments, Deploy Enforcement, and Stack Management. Replaces
the readiness board screenshot with a fresh production capture and
removes three orphaned screenshots left over from the page's prior
CRUD-policy layout.
* docs(auto-heal-policies): refresh against current live app and source
Correct the admin-only prerequisite: viewing policies and history is
open to every signed-in role, only creating/toggling/deleting requires
admin. Rewrite the matching troubleshooting entry to match, note the
overlap behavior between an All-services and a named-service policy on
the same container, and replace all three screenshots with a real
production policy.
* docs(webhooks): refresh against current live app and source
Replaced all three screenshots with fresh production captures (single
webhook create/reveal flow, two-card configured list), verified every
claim against WebhookService/StackOpLockService/registry.ts, and added
the previously undocumented per-stack lock skip behavior for
non-Git-source-sync actions with a matching troubleshooting entry.
* docs(global-observability): refresh against current live app and source
* docs(audit-log): refresh against current live app and source
- Fix nav terminology: Audit is a top navigation tab, not a sidebar tab.
- Correct retention claim: Admiral shows full retained history (default
90 days), not a fixed 14-day window; the 14-day clamp only applies to
the Community API, which has no navigation entry point at all.
- Fix settings path: Settings - Operations - Data Retention (previously
pointed at the now-split Developer Diagnostics section).
- Restore current Recovery Vault naming (was stale Sencho Cloud Backup).
- Expand the tracked-actions list: stack take-down, label management,
MFA reset, and notification suppression rules were missing.
- Note that assigning the Auditor role itself requires Admiral.
- Replace all four screenshots with fresh production captures (Stream,
Table, expanded row, Data Retention) reflecting the current five-row
retention card.
* fix(audit-log): reframe data-retention screenshot to card content only
The prior crop included the Settings sub-navigation panel, which isn't
part of what the surrounding text describes. Retake tightly cropped to
match the page's other screenshots (card content only, no chrome).
* docs(multi-node): refresh against current live app and source
Rewrites the Pilot Agent enrollment flow (now a generated compose.yaml
plus docker compose up -d, not a single docker run command) and the
Settings scope table (current registry: Stacks, Container Alerts,
Docker & Storage, Data Retention, Mute Rules, Recovery, and the
Admiral Account / Recovery Vault renames). Adds a Sencho Mesh
cross-link matching the live add-node form copy. Replaces all eight
screenshots with sanitized production captures.
* docs(pilot-agent): refresh against current live app and source
* docs(readme): refresh GitHub README against current live app
Replace all 9 screenshots (stale top nav showing a removed Console
item and missing the new Networking page); document Take down,
Drift Detection, Environment and Secrets Guardrails, Storage
Portability, Docker Label Audit, Remote Updates, and the node-wide
Networking dashboard; fix a broken non-root-user anchor link; correct
the notification channels list (no email channel exists yet) and the
global search scope (pages, nodes, and stacks, not containers or
services); rename "scan policy packs" to the current "scan policies"
terminology; broaden the App Store bullet to cover custom registries.
* docs(readme): reposition intro copy and refresh badge row
Lead with DevOps/platform/sysadmin framing instead of homelab-first,
drop pre-1.0 "production" language, state plainly that Sencho
provides a UI instead of promotional "does the work you do" phrasing,
and call out that multi-node was part of the architecture from the
start. Swap the Discussions badge for CodeQL, last-commit, open
issues, and live website/docs status badges, and add a blog link.
* docs: retake Dashboard and Global Search screenshots for accuracy
Configuration Status now shows Recovery Vault instead of the stale
Cloud Backup label, and the search palette capture includes the
Networking page entry added after the prior screenshot batch.
* docs: refresh Fleet View page against current app
Fleet View has drifted since its last rewrite: the Docker Labels tab,
Export Dossier action, Networking filter/badge, node label pills and
latency in topology, the Policy sync status row, and the node card
Mute submenu were all shipped but undocumented. The Check Updates and
Add Node actions also moved into the Overview toolbar (renamed Node
Update / Manage Nodes) and no longer sit in the shared action row.
Replaces all five screenshots with fresh production captures and
corrects the masthead's motion description (a calm shimmer on Healthy,
a steady glow on Degraded/Critical, not a pulsing dot). Also fixes a
Fleet Sync limitation that claimed no first-party sync-status panel
exists, now that the Status tab surfaces one.
* docs: refresh Fleet Dossier page against current app
Adds the page's first screenshot, documents the network exposure summary now included per stack, documents the storage-summary omission versus the Stack Dossier export, and adds two troubleshooting entries.
* docs(fleet-federation): deep rewrite for the rollout-approval gate
Federation's cordon and pin controls no longer take effect by
themselves: the reconciler requires a confirmed rollout preview
(Apply now -> Confirm Apply) before it mutates the fleet, and pinning
or unpinning always clears a blueprint's approval. Rewrote the mental
model, step-by-step, lifecycle table, security section, limitations,
practical workflows, troubleshooting, and cross-links to reflect that
gate. Also corrected the audit-log claims: cordon/uncordon/pin are not
filterable by a node.cordon/blueprint.pin action taxonomy, only by the
free-text search box against the method, path, and summary.
Replaced 4 screenshots and added 3 new ones (production fleet plus an
isolated instance to capture the rollout preview dialog in both a
safe and a blocked state), and fixed one stale pin-workflow sentence
in blueprint-model.mdx that the same audit surfaced.
* docs(fleet-federation): drop tier-availability framing
The feature isn't tier-gated, so calling out "every tier" reads as an
unnecessary advertisement. Removed the tier note and the Community/
Admiral prerequisite row, and reworded two role-visibility sentences
that had conflated tier with role.
* docs(fleet-actions): deep rewrite for the v2 action-card redesign
Rewrites the page against the shipped Fleet Action Card redesign: a
single cyan rail with per-card action-class chips instead of the old
per-card rose/purple/amber rails, plus the live blast-radius preview,
dry-run, and confirmed-target binding mechanics that replaced the old
static warning banners. Documents two previously-undocumented
endpoints (match-preview, prune/estimate), the preview-confirm-execute
model shared by all three cards, per-node locking, timeouts, and the
version-gated confirmed-target contract for mixed-version fleets. All
five screenshots recaptured against the live production UI.
* docs(fleet-actions): fix nested quote in screenshot alt text
* docs(fleet-sync): refresh against current app and document proxy gap
Retake all screenshots against the live fleet (control authoring view,
a genuine replica showing the read-only banner, and replicated
suppression rows) and document a previously-unwritten behavior: scan
policies, CVE suppressions, and misconfig acknowledgements are fetched
localOnly and are not proxied through the node switcher like most
other Security page tabs, so viewing a remote's Fleet Sync state
requires signing into that instance directly.
* docs(fleet-backups): refresh against current app and note new integration points
Replaces all 6 screenshots with fresh 1920x1080 production captures and
corrects several drifted details: the Cloud Snapshots panel's pagination
and per-item delete action, the exact Recovery Vault storage-mode label,
and the real per-file size-cap behavior (an oversized compose.yaml skips
the whole stack; an oversized .env is dropped but the stack still
captures). Documents two entry points that were missing from the page:
the pre-update snapshot checkbox in Health-Gated Updates and the snapshot
coverage nudge on the Storage Portability tab. Expands the single warning
banner description in the detail view to cover all four banner types,
notes the Snapshots tab and Recovery Vault are hub-only, and adds a
Where Fleet Backups fits table cross-linking the six adjacent features.
* docs(remote-updates): refresh against current app and add hardened-channel notes
Replace all screenshots with fresh 1920x1080 production captures and fix the
Node Updates trigger label (Check Updates -> Node Update). Add the Changelog
tab, correct the reconnect overlay's stale 'Update timed out'/Try Reloading
copy to the current Taking longer than expected/Reload to check text, and
document the Admiral Hardened Build channel's carve-outs (pinned-but-not-blocked,
entitlement-gated local update path). Disambiguate this page from the
unrelated top-level Update (Health-Gated Updates) nav tab.
* docs(node-compatibility): refresh against current app and expand capability list
Replace all screenshots with fresh production captures (node switcher,
capability lock card, connection test panel) and swap the lock-card example
from a now-hidden Host Console to Audit Log, which is directly reachable.
Bring the capability table from 26 to 35 entries to match the current
registry, add a Mute Rules row, and split out fine-grained fallback
capabilities (update-guard, service-scoped-update, cross-node-rbac,
stack-down-remove-volumes) with their non-lock-card fallback behavior.
Fix the compose-networking row, which incorrectly claimed to also gate the
node-level Networking overview. Note that Pilot Agent nodes never advertise
host-console regardless of version.
* docs(security): refresh against current app and document scan-node launcher
Replaces all screenshots with fresh production captures, documents the
Scan this node launcher and the third Scanner setup toggle (pre-deploy
scan advisory), tightens the Compose risks example list and the Policies
block-condition description to match the live app, and adds an On a
phone section.
* docs(vulnerability-scanning): refresh for exploit intel and risk-based policies
Documents exploit intelligence (KEV/EPSS evidence tags), the redesigned
risk-based scan policies (severity/known-exploited/fixable block
conditions replacing the single max-severity field), and the new
Findings badge state. Replaces all screenshots with fresh production
captures and adds a Secrets tab example.
* docs: refresh CVE suppressions page
Retook all screenshots against production (prior ones predated the
triage-status/OpenVEX UI and the edit capability). Documented the
suppression edit flow, which the page previously described as
delete-and-recreate only. Corrected the remote-node banner copy on the
Suppressions tab and added a screenshot of it. Cross-linked the
Misconfig acknowledgements panel that now sits on the same tab.
* docs(two-factor-authentication): refresh screenshots and document rate-limit layers
Replace all 11 non-count-variant screenshots with fresh production captures.
Document the throttled sign-in state precisely (kicker/hero/caption change,
not just the input), that a replayed TOTP counts toward the lockout counter,
and the separate per-network-address sign-in rate limit that sits in front
of the per-account MFA lockout.
* docs(api-tokens): refresh screenshots and document service-scoped deploy actions
Deploy Only now authorizes eight lifecycle POSTs (was six): the per-service
update and restore endpoints were missing from the scope table. Universal
restrictions gained a row for image channel management, which was already
rejecting API tokens in code but undocumented. Replaced all five screenshots
with fresh captures showing the current three-scope create flow and a
populated list with one token of each scope.
* docs(upgrade): refresh against current app and remove legacy-version framing
Fixes migration-list inaccuracies (registry credentials were never
plaintext, unlike node API tokens), rephrases the SSH/TLS and JSON-config
migration bullets to drop version-numbered legacy framing, adds a GHCR
mirror note matching the quickstart pattern, and cross-links the Hardened
Build entitlement-gated update path so digest-pinned installs aren't sent
down the manual docker pull steps.
* docs: refresh Backup & Restore against current backend
Broadens the encryption.key warning to cover everything CryptoService
actually encrypts (node tokens, Git source and Fleet Secrets, SSO/MFA,
Recovery Vault, fleet snapshot contents), not just registry credentials.
Adds the built-in backupData CLI as a no-host-tooling alternative to the
sqlite3 .backup command, cross-linked to Emergency command-line recovery.
Corrects node-token migration guidance: tokens are signed with a secret
stored in sencho.db and remain valid after a host move, so no
regeneration is required.
* docs: refresh Recovery guide against current Settings page and CLI
Documents the Settings · Recovery page's full System health / Environment /
Safe actions / Command-line hub instead of only its environment-preflight
section, adds the missing "Sencho compose location" preflight check, adds the
SSO/OIDC/LDAP lockout scenario now that disableSso.js exists, and corrects the
rollback description (exact UI label, backup-required and image-layer caveats).
* docs(emergency-cli): sync in-app page description, add CLI operational details
Aligns the "in-app Recovery page" summary with the freshly refreshed Recovery
guide (System health / Environment / Safe actions / Command-line recovery, SSO
providers, one-click command download). Adds constraints verified against the
CLI source: password/username minimums, the valid SSO provider identifiers with
an example, and a note that diagnostics.js always reports Docker as unreachable
(it runs without a live Docker connection, unlike the in-app page).
* docs(troubleshooting): refresh against current backend and nav
Corrects several claims that had drifted from the implementation:
network name validation (underscore is not a valid leading character),
the remote-update delayed-failure window (3 minutes, not 90 seconds),
and an unsubstantiated version-compatibility check on the Admiral 403
entry. Removes two entries describing legacy pre-v0.39 node behavior
that no longer applies to any currently shipped build. Replaces stale
"Profile > Settings > X" navigation with the current Settings hub
paths, and "wifi icon" with the current Test Connection label. Adds
Pilot Agent awareness to the remote-offline entry with a cross-link to
its dedicated troubleshooting section, and trims the docker-run
converter entry to point at the fuller, already-current version on the
Stack Management page instead of duplicating it with a broken anchor.
* docs(verifying-images): document the :dev GHCR integration tag
Verified the existing cosign/SBOM/VEX/tag-policy content against
docker-publish.yml and docker-preview.yml; all accurate. Added the
previously undocumented :dev/:dev-<sha> integration tag published on
every push to main via docker-dev.yml.
* docs(trivy-setup): sync install guide with node-scoped scanner and current Trivy upstream docs
Documents that Trivy installs independently per node, adds the TRIVY_BIN
override and non-PATH mounting option, fixes the deprecated apt-key install
flow and RHEL repo gpgkey placement, notes the Exploit intelligence toggle
for air-gapped hosts, and replaces the stale Scanner setup screenshot.
* docs(two-factor-admin): document lockout recovery and self-reset gotcha
Verified the reset flow, CLI recovery, and SSO toggle claims against
current source and replaced the stale admin-reset modal screenshot.
Added the failed-attempt lockout behavior (undocumented despite being
promised in the page description) and a warning about resetting your
own 2FA from the Users list, which signs you out immediately unlike
the self-service disable flow.
* fix(docs): make Settings and Self-hosting discoverable in the sidebar
The Reference and Operations groups used root pages that were only
reachable by clicking the ambiguous group label, and that click also
triggered an unwanted double action (expand plus navigate). List both
pages as explicit sidebar entries and disable global drilldown so group
headers only expand or collapse.
* docs(settings): sync reference page with current Settings Hub
Renamed License to Admiral Account throughout (Hardened Build channel
switch, image channel display, DURATION pill), corrected the password
policy, documented the new Appearance navigation and log-chip-color
controls plus font options, noted Mesh data plane is not on every
installation, fixed the label cap (50, not 100), and replaced every
screenshot with a fresh capture from the production node.
* fix(docs): apply the sidebar toggle-only fix to Start here and Product guide
These two groups had the same click-to-navigate-and-expand pattern as
Reference and Operations. Flattening them is safe here too: the
Product guide root page has no directory listing depending on it, and
the Start here root page's own hand-authored Next steps CardGroup
already covers the same links the auto-generated listing duplicated.
* docs(licensing): refresh licensing page for Hardened Build and sales-led Admiral pricing
Admiral pricing moved from self-serve checkout to a contact-sales model, and
a new Hardened Build image-channel switcher shipped in the Admiral Account
settings page; neither was reflected in the docs. Also documents the
lifetime-license edge case (no Manage subscription button, no Billing row)
and refreshes all four screenshots against the current UI.
* docs(security): sync reference page with current API-token and encryption scope
Verified every claim against the live implementation: the API-token universal
restrictions list was missing MFA management, Recovery Vault, and image
channel management; the encryption-at-rest field list was missing Recovery
Vault credentials; added a note on the password strength indicator's
recommended-vs-enforced distinction. Refreshed the SSO settings, API tokens,
and audit log screenshots against the production node.
* docs(settings): fix password policy and session-invalidation claims
Cross-checked against auth.ts while verifying the same claims on the
security reference page: the enforced minimum is 8 characters (the
12+/mixed-case/number text is a frontend strength hint, not a validated
rule), and a password change invalidates every other session for the
account rather than leaving them valid.
* docs(contact): sync contact channels with sales-led pricing and current support gating
Replace the retired contact@sencho.io with hello@sencho.io (the address actually
used in the website footer and the pricing page's Get in touch CTA), narrow the
licensing@sencho.io scope to existing-license activation/billing/refunds now that
new Admiral conversations route through hello@sencho.io, drop the stale LICENSE-file
and in-app upgrade-prompt claims (the AGPLv3 relicense removed both), correct the
Support settings path and add the published response-time targets, and remove the
unsubstantiated bug bounty mention.
This commit is contained in:
Anso
@@ -19,10 +19,10 @@ Default path: `/app/data` inside the container, mapped to wherever you mounted i
|
||||
|
||||
Contains:
|
||||
- `sencho.db` - SQLite database with all settings, users, nodes, alerts, metrics history, and notification config
|
||||
- `encryption.key` - Key used to encrypt sensitive values (registry credentials, node API tokens) stored in the database
|
||||
- `encryption.key` - Key used to encrypt sensitive values stored in the database: registry credentials, node tokens for remote nodes, Git source credentials, [Fleet Secrets](/features/fleet-secrets) bundles, SSO and MFA secrets, Recovery Vault credentials, and the contents of every [Fleet Snapshot](/features/fleet-backups)
|
||||
|
||||
<Warning>
|
||||
Both files are required for a full restore. If you restore `sencho.db` without the matching `encryption.key`, any encrypted values in the database will be unreadable and you will need to re-enter registry credentials and re-generate node API tokens.
|
||||
Both files are required for a full restore. If you restore `sencho.db` without the matching `encryption.key`, every encrypted value in the database becomes permanently unreadable: registry credentials, remote node tokens, Git source and Fleet Secrets bundles, SSO/MFA configuration, and the compose file contents inside any existing fleet snapshot. There is no way to recover this data without the original key; you would need to re-enter each credential, re-enroll remote nodes, and re-capture any snapshots you rely on.
|
||||
</Warning>
|
||||
|
||||
### 2. Compose directory (`COMPOSE_DIR`)
|
||||
@@ -57,7 +57,7 @@ docker start sencho
|
||||
|
||||
### SQLite online backup (without stopping)
|
||||
|
||||
SQLite supports hot backups via its `.backup` command. This is safe to run while Sencho is running:
|
||||
SQLite supports hot backups via its `.backup` command. This is safe to run while Sencho is running, and requires the `sqlite3` CLI to be installed on the host:
|
||||
|
||||
```bash
|
||||
sqlite3 /path/to/sencho-data/sencho.db ".backup '/path/to/backup/sencho.db'"
|
||||
@@ -65,13 +65,23 @@ sqlite3 /path/to/sencho-data/sencho.db ".backup '/path/to/backup/sencho.db'"
|
||||
|
||||
Remember to also copy `encryption.key` from the same directory.
|
||||
|
||||
### Built-in backup command (no host tooling required)
|
||||
|
||||
Sencho ships an equivalent online backup as a CLI command that runs inside the container, so you do not need `sqlite3` on the host:
|
||||
|
||||
```bash
|
||||
docker compose exec sencho node dist/cli/backupData.js [destination-dir]
|
||||
```
|
||||
|
||||
With no destination argument it writes a timestamped folder under `DATA_DIR/backups`, copies `sencho.db` and `encryption.key` together, and records the action in the audit log. See [Emergency command-line recovery](/operations/emergency-cli#back-up-the-data-directory) for the full command reference.
|
||||
|
||||
### Automated daily backup (cron example)
|
||||
|
||||
```cron
|
||||
0 3 * * * cp /path/to/sencho-data/encryption.key /backups/encryption.key && sqlite3 /path/to/sencho-data/sencho.db ".backup '/backups/sencho-$(date +\%Y\%m\%d).db'" && find /backups -name "sencho-*.db" -mtime +30 -delete
|
||||
```
|
||||
|
||||
This copies the encryption key, backs up the database at 3 AM daily, and deletes database backups older than 30 days.
|
||||
This copies the encryption key, backs up the database at 3 AM daily, and deletes database backups older than 30 days. If the host does not have `sqlite3` installed, substitute `docker compose exec sencho node dist/cli/backupData.js /backups/sencho-$(date +\%Y\%m\%d)` for the same effect.
|
||||
|
||||
---
|
||||
|
||||
@@ -130,7 +140,7 @@ docker compose up -d
|
||||
|
||||
### Step 4: Update remote node references
|
||||
|
||||
If other Sencho instances were pointing to your old host as a remote node, update their node config to use the new host's IP or hostname. Generate a new API token on the restored instance and distribute it.
|
||||
If other Sencho instances were pointing to your old host as a remote node, update their node config to use the new host's IP or hostname. Node tokens are JWTs signed with a secret stored in `sencho.db`, so any token issued before the move is copied along with your data and keeps working automatically; you only need to update the URL, not regenerate the token. Generate a fresh one from **Settings → Infrastructure → Nodes** only if you want to rotate it for its own sake.
|
||||
|
||||
### Step 5: Verify
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Emergency command-line recovery
|
||||
sidebarTitle: Emergency CLI
|
||||
description: Host-level commands that recover access when the Sencho UI is unreachable, plus the in-app Recovery surface for everyday health checks.
|
||||
description: Host-level commands that recover access when the Sencho UI is unreachable, plus a pointer to the in-app Recovery page for everyday health checks.
|
||||
---
|
||||
|
||||
When the dashboard is unreachable, an identity provider blocks the login screen, or every administrator is locked out, Sencho ships a set of emergency commands you run from a shell on the host. Each one acts on the same SQLite database the application uses (it respects the container's `DATA_DIR`), and each writes an audit-log entry attributed to `cli` where it changes state, so the action is traceable afterwards.
|
||||
@@ -18,11 +18,11 @@ Each command prints what it did and exits with code `0` on success or non-zero o
|
||||
Before you rely on Sencho in earnest, back up `DATA_DIR` and `COMPOSE_DIR`. The [Recovery guide](/operations/recovery) explains why most recovery is file-level, and [Backup & Restore](/operations/backup) gives a copy-and-restore routine.
|
||||
</Note>
|
||||
|
||||
## In-app Recovery surface
|
||||
## The in-app Recovery page
|
||||
|
||||
For everyday checks you do not need a shell. An administrator can open **Settings · Recovery** for a read-only health snapshot: app version, database integrity, encryption-key status, Docker reachability, administrator and two-factor counts, and the non-secret configuration. The page loads without Docker or live metrics, so it stays available when the rest of the dashboard does not. From there you can export the snapshot as JSON, reset this browser's interface preferences to defaults, and see the same command reference printed below.
|
||||
For everyday checks you do not need a shell. **Settings · Recovery** is a read-only hub: a System health snapshot (app version, database integrity, encryption-key status, Docker reachability, administrator and two-factor counts, and configured SSO providers, exportable as JSON), the Environment preflight checks, Safe actions such as resetting this browser's interface preferences, and this same command reference with a one-click download. The page loads without Docker or live metrics, so it stays available when the rest of the dashboard does not.
|
||||
|
||||
The command line is the fallback for when even that surface cannot be reached.
|
||||
See the [Recovery guide](/operations/recovery) for a full walkthrough of that page and every failure scenario it covers. The command line below is the fallback for when even that page cannot be reached.
|
||||
|
||||
## Sign-in and account recovery
|
||||
|
||||
@@ -34,7 +34,7 @@ Resets a local user's password and signs out their existing sessions.
|
||||
docker compose exec sencho node dist/cli/resetPassword.js <username> <new-password>
|
||||
```
|
||||
|
||||
Applies to local accounts only. Users who sign in through SSO are managed by their identity provider.
|
||||
The new password must be at least 8 characters. Applies to local accounts only; users who sign in through SSO are managed by their identity provider.
|
||||
|
||||
### Create an emergency administrator
|
||||
|
||||
@@ -44,7 +44,7 @@ Creates a fresh local administrator when every existing admin is locked out but
|
||||
docker compose exec sencho node dist/cli/createEmergencyAdmin.js <username> <password>
|
||||
```
|
||||
|
||||
It refuses to overwrite an existing user; use the password reset above for an account that already exists. Sign in afterwards and review your other accounts.
|
||||
The username must be at least 3 characters (letters, numbers, underscore, and hyphen only) and the password at least 8. It refuses to overwrite an existing user; use the password reset above for an account that already exists. Sign in afterwards and review your other accounts.
|
||||
|
||||
### Clear the existing two-factor enrolment
|
||||
|
||||
@@ -74,18 +74,28 @@ Re-enables local password sign-in when a misconfigured identity provider blocks
|
||||
docker compose exec sencho node dist/cli/disableSso.js [provider]
|
||||
```
|
||||
|
||||
`provider` is one of the identifiers used in **Settings · SSO** (`ldap`, `oidc_google`, `oidc_github`, `oidc_okta`, or `oidc_custom`), for example:
|
||||
|
||||
```bash
|
||||
docker compose exec sencho node dist/cli/disableSso.js oidc_google
|
||||
```
|
||||
|
||||
With no argument it disables every enabled provider. The stored configuration is preserved (only the enabled flag is cleared), so you can correct it and turn it back on from **Settings · SSO**.
|
||||
|
||||
## Inspecting and protecting your data
|
||||
|
||||
### Print a diagnostic summary
|
||||
|
||||
Prints the same snapshot the in-app Recovery surface shows, as JSON. Read-only and free of secrets, so it is safe to paste into a bug report.
|
||||
Prints the same snapshot the in-app Recovery page shows, as JSON. Read-only and free of secrets, so it is safe to paste into a bug report.
|
||||
|
||||
```bash
|
||||
docker compose exec sencho node dist/cli/diagnostics.js
|
||||
```
|
||||
|
||||
<Note>
|
||||
The `docker` field always reports `reachable: false` in this command's output: the CLI runs without a live Docker connection, unlike the in-app Recovery page, which probes the socket directly. That does not indicate a problem; check Docker from the in-app page or `docker ps` on the host instead.
|
||||
</Note>
|
||||
|
||||
### Validate the database and encryption key
|
||||
|
||||
Runs a database integrity check, confirms the core tables exist, confirms the encryption key is present and usable, and confirms at least one administrator exists. Exits non-zero if any check fails.
|
||||
|
||||
@@ -18,13 +18,26 @@ Your compose files on disk are always the source of truth. Sencho reads them; it
|
||||
|
||||
---
|
||||
|
||||
## The in-app Recovery page
|
||||
|
||||
Before reaching for a shell, check **Settings · Recovery**. It is a single read-only hub built for exactly the moments this guide covers:
|
||||
|
||||
- **System health**: a live snapshot of the database, encryption key, Docker reachability, administrator and two-factor counts, and configured SSO providers, exportable as JSON for a bug report.
|
||||
- **Environment**: the preflight checks described below, with a re-run button.
|
||||
- **Safe actions**: reset this browser's interface preferences, and a link back to this guide.
|
||||
- **Command-line recovery**: every emergency command listed below, with a one-click download of the full reference as a text file, so you have it on hand before you need a shell.
|
||||
|
||||
The page loads without Docker or live metrics, so it stays available when the rest of the dashboard does not.
|
||||
|
||||
## Environment checks
|
||||
|
||||
Sencho runs a short environment preflight as the final step of first-boot setup, and you can re-run it anytime from **Settings · Recovery**. It confirms the things a deploy depends on, so a deploy does not fail for an avoidable reason:
|
||||
|
||||
- the Docker engine is reachable and Sencho has permission to talk to the socket,
|
||||
- the Docker Compose plugin is present,
|
||||
- the compose directory exists, is writable, and is mounted at a matching host path (the [1:1 path rule](/getting-started/configuration#compose-directory-the-11-path-rule)),
|
||||
- the compose directory exists and is writable,
|
||||
- Sencho's own compose project is not nested inside `COMPOSE_DIR` (managing itself as a regular stack would create a conflict with self-updates),
|
||||
- the compose directory is mounted at a matching host path (the [1:1 path rule](/getting-started/configuration#compose-directory-the-11-path-rule)),
|
||||
- the dashboard is reached over TLS rather than plain HTTP,
|
||||
- and the compose volume has disk headroom.
|
||||
|
||||
@@ -65,7 +78,7 @@ See [Backup & Restore](/operations/backup#restoring) for the restore steps and [
|
||||
docker compose -f /path/to/your/stack/compose.yaml logs
|
||||
```
|
||||
2. The usual causes are a missing environment variable, a host port already in use, or a bind-mount path that does not exist yet. Each is fixed in the compose file or `.env`.
|
||||
3. If a previously working stack broke after an edit, use **one-click rollback** in the editor to return to the last deployed version of the compose file.
|
||||
3. If a previously working stack broke after an edit, use **Rollback** from the stack's overflow menu to revert the compose and env files to the last deployed snapshot and redeploy. It is only offered when a pre-deploy backup exists, and it restores the files, not previously built image layers.
|
||||
|
||||
See [Troubleshooting: containers won't start after deploy](/operations/troubleshooting#containers-wont-start-after-deploy) for the full cause list and [Stack management](/features/stack-management) for the editor and rollback.
|
||||
|
||||
@@ -73,14 +86,15 @@ See [Troubleshooting: containers won't start after deploy](/operations/troublesh
|
||||
|
||||
## You are locked out of sign-in
|
||||
|
||||
**Symptom:** An administrator has lost their second factor, or the admin password is forgotten, and no one can sign in through the UI.
|
||||
**Symptom:** An administrator has lost their second factor, the admin password is forgotten, or a misconfigured identity provider blocks the login screen entirely, and no one can sign in through the UI.
|
||||
|
||||
**What to do, least disruptive first:**
|
||||
|
||||
1. **Another admin is still in:** any administrator can reset a locked-out user's two-factor enrolment from **Settings · Users**. The user then signs in with their password alone and re-enrols.
|
||||
2. **Every admin has lost 2FA:** reset two-factor for the admin account directly on the host with the emergency command-line reset. It acts on the same database the app uses and records the action in the audit log.
|
||||
3. **The admin password itself is forgotten:** Sencho has no password-reset email flow, but you do not need to discard your configuration. From a shell on the host, reset the password with the emergency command line, or create a fresh emergency administrator. Both act on the live database and leave your nodes, alert rules, and labels untouched.
|
||||
4. **Last resort, the database is unusable:** reset first-boot setup by removing `sencho.db`, which lets you create a fresh admin account from scratch.
|
||||
1. **A misconfigured SSO/OIDC/LDAP provider blocks the login screen:** disable it from the host with the emergency command line. The stored configuration is preserved, only the enabled flag is cleared, so local password sign-in becomes reachable again and you can correct and re-enable the provider from **Settings · SSO**.
|
||||
2. **Another admin is still in:** any administrator can reset a locked-out user's two-factor enrolment from **Settings · Users**. The user then signs in with their password alone and re-enrols.
|
||||
3. **Every admin has lost 2FA:** reset two-factor for the admin account directly on the host with the emergency command-line reset. It acts on the same database the app uses and records the action in the audit log.
|
||||
4. **The admin password itself is forgotten:** Sencho has no password-reset email flow, but you do not need to discard your configuration. From a shell on the host, reset the password with the emergency command line, or create a fresh emergency administrator. Both act on the live database and leave your nodes, alert rules, and labels untouched.
|
||||
5. **Last resort, the database is unusable:** reset first-boot setup by removing `sencho.db`, which lets you create a fresh admin account from scratch.
|
||||
|
||||
<Warning>
|
||||
Removing `sencho.db` resets all Sencho configuration: users, nodes, alert rules, notification settings, and labels. Your Docker stacks and their compose files are not affected, and Sencho re-discovers them on the next scan. Use this only when no administrator can sign in and the command-line recovery above is not enough.
|
||||
|
||||
@@ -11,6 +11,10 @@ Sencho's [Vulnerability Scanning](/features/vulnerability-scanning) feature uses
|
||||
|
||||
Once Trivy is available through any of these options, the scanning UI appears automatically.
|
||||
|
||||
<Note>
|
||||
Trivy is installed independently on each node. In a fleet, the Scanner setup tab manages the scanner for whichever node is active, so repeat one of the options above on every node you want to scan images on.
|
||||
</Note>
|
||||
|
||||
## Why Trivy is not bundled
|
||||
|
||||
Trivy's vulnerability database updates multiple times per day and is around 100 MB. Bundling Trivy would force every Sencho instance to carry an out-of-date database in its image, then re-download on first scan. Keeping Trivy external lets you:
|
||||
@@ -28,7 +32,7 @@ Sencho can install and manage Trivy for you without any extra bind mounts or env
|
||||
3. Wait for the status to flip to **Installed (managed)**. The version appears next to the badge.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/vulnerability-scanning/trivy-settings-card.png" alt="Vulnerability Scanner card on the Security page Scanner setup tab, with Install Trivy button" />
|
||||
<img src="/images/vulnerability-scanning/trivy-settings-card.png" alt="Vulnerability Scanner card on the Security page Scanner setup tab, showing a managed install with the Auto-update Trivy, Pre-deploy scan advisory, and Exploit intelligence toggles" />
|
||||
</Frame>
|
||||
|
||||
Behind the scenes:
|
||||
@@ -49,7 +53,7 @@ The install, update, and uninstall buttons and the **Auto-update Trivy** toggle
|
||||
|
||||
### Removing the managed install
|
||||
|
||||
Click **Uninstall** next to the status badge. Sencho removes the binary from `/app/data/bin/trivy`. The vulnerability database cache at `/app/data/trivy-cache` is left in place in case you reinstall later; delete it manually if you want to reclaim the disk space.
|
||||
Click **Uninstall** next to the status badge and confirm in the dialog. Sencho removes the binary from `/app/data/bin/trivy`; vulnerability scanning stops working until Trivy is reinstalled or a host binary is provided. The vulnerability database cache at `/app/data/trivy-cache` is left in place in case you reinstall later; delete it manually if you want to reclaim the disk space.
|
||||
|
||||
## Option 2: Installing Trivy on the host
|
||||
|
||||
@@ -57,8 +61,8 @@ Click **Uninstall** next to the status badge. Sencho removes the binary from `/a
|
||||
|
||||
```bash
|
||||
sudo apt-get install wget gnupg
|
||||
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | sudo apt-key add -
|
||||
echo "deb https://aquasecurity.github.io/trivy-repo/deb generic main" | sudo tee /etc/apt/sources.list.d/trivy.list
|
||||
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | gpg --dearmor | sudo tee /usr/share/keyrings/trivy.gpg > /dev/null
|
||||
echo "deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb generic main" | sudo tee /etc/apt/sources.list.d/trivy.list
|
||||
sudo apt-get update
|
||||
sudo apt-get install trivy
|
||||
```
|
||||
@@ -66,12 +70,12 @@ sudo apt-get install trivy
|
||||
### Linux (RHEL / Fedora)
|
||||
|
||||
```bash
|
||||
sudo rpm --import https://aquasecurity.github.io/trivy-repo/rpm/public.key
|
||||
echo "[trivy]
|
||||
name=Trivy repository
|
||||
baseurl=https://aquasecurity.github.io/trivy-repo/rpm/releases/\$basearch/
|
||||
gpgcheck=1
|
||||
enabled=1" | sudo tee /etc/yum.repos.d/trivy.repo
|
||||
enabled=1
|
||||
gpgkey=https://aquasecurity.github.io/trivy-repo/rpm/public.key" | sudo tee /etc/yum.repos.d/trivy.repo
|
||||
sudo dnf install trivy
|
||||
```
|
||||
|
||||
@@ -91,7 +95,7 @@ The command should print a `Version: X.Y.Z` line. Note the path that `which triv
|
||||
|
||||
## Making a host-installed Trivy available to Sencho
|
||||
|
||||
If you already installed Trivy on the host (Option 2) and prefer to manage it externally, Sencho runs inside a container and looks for `trivy` on its own `PATH`. There are two ways to expose it:
|
||||
If you already installed Trivy on the host (Option 2) and prefer to manage it externally, Sencho looks for a binary in this order: the managed install, then the path in `TRIVY_BIN` if set, then `trivy` on the container's own `PATH`. There are two ways to expose a host binary:
|
||||
|
||||
### Bind mount the host binary
|
||||
|
||||
@@ -119,7 +123,20 @@ The `trivy-cache` volume persists the vulnerability database across Sencho conta
|
||||
|
||||
Adjust the first path if `which trivy` on the host prints something other than `/usr/local/bin/trivy` (for example `/usr/bin/trivy` on some distributions).
|
||||
|
||||
### Option 3: Build a custom Sencho image
|
||||
### Mounting to a non-PATH location
|
||||
|
||||
If you would rather not put the binary on `PATH` inside the container, mount it anywhere and point `TRIVY_BIN` at it instead:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
sencho:
|
||||
volumes:
|
||||
- /opt/trivy/trivy:/opt/trivy/trivy:ro
|
||||
environment:
|
||||
- TRIVY_BIN=/opt/trivy/trivy
|
||||
```
|
||||
|
||||
## Option 3: Build a custom Sencho image
|
||||
|
||||
If the host's Trivy binary is not ABI-compatible with the Sencho container (for example because you are running macOS host binaries or a different glibc version), install Trivy inside the image instead:
|
||||
|
||||
@@ -180,10 +197,16 @@ Trivy supports offline use through pre-built database bundles.
|
||||
|
||||
Plan to refresh the bundle on a schedule (weekly is typical) so CVE data stays current.
|
||||
|
||||
The Scanner setup tab also has an **Exploit intelligence (KEV + EPSS)** toggle, on by default, that independently reaches `cisa.gov` and `api.first.org` once a day to prioritize findings. It is unrelated to the Trivy database bundle above, so turn it off separately if the host must not make any outbound calls at all.
|
||||
|
||||
## Verifying Sencho detects Trivy
|
||||
|
||||
1. Open the **Security** page → **Scanner setup** tab. The **Vulnerability Scanner** card shows the current status and version.
|
||||
2. Open the **Resources** tab. If Trivy is detected, a shield icon appears in the Actions column of the **Images** panel next to the delete icon on every row.
|
||||
2. Open the **Resources** page → **Images** tab. If Trivy is detected, a shield icon appears in the Action column next to the delete icon on every row with a tag.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/vulnerability-scanning/resources-badges.png" alt="Resources page Images tab with the scan (shield) icon in the Action column of every row" />
|
||||
</Frame>
|
||||
|
||||
If the scanner shows as not installed after using Option 2 or 3, see the troubleshooting section below.
|
||||
|
||||
@@ -203,7 +226,7 @@ Verify the binary is visible from inside the container:
|
||||
docker exec sencho trivy --version
|
||||
```
|
||||
|
||||
If the command returns "not found", the mount path inside the container is wrong. The binary must be on `PATH`. Both `/usr/local/bin/trivy` and `/usr/bin/trivy` work.
|
||||
If the command returns "not found", the mount path inside the container is wrong. The binary must either be on `PATH` (`/usr/local/bin/trivy` and `/usr/bin/trivy` both work) or match the path set in `TRIVY_BIN`.
|
||||
|
||||
### Binary exists but reports an exec format error
|
||||
|
||||
@@ -215,7 +238,7 @@ The first scan after a Trivy install downloads the vulnerability database. Expec
|
||||
|
||||
### Install button is hidden
|
||||
|
||||
The install button is hidden when a host-installed Trivy is already detected on `PATH`. Remove the host binary (or drop the bind mount) to switch to the managed install. The button also requires the admin role; viewer accounts see the scanner status only.
|
||||
The install button is hidden when a host-installed Trivy is already detected, whether via `TRIVY_BIN` or on `PATH`. Remove the host binary (or drop the bind mount and unset `TRIVY_BIN`) to switch to the managed install. The button also requires the admin role; viewer accounts see the scanner status only.
|
||||
|
||||
### Private registry images fail to scan
|
||||
|
||||
|
||||
@@ -168,14 +168,16 @@ Traefik handles WebSocket upgrades automatically for HTTP/1.1 backends, so no ex
|
||||
|
||||
**Symptom:** A node you added shows a red or gray status dot.
|
||||
|
||||
**Checks in order:**
|
||||
Sencho connects to a remote node one of two ways: **Distributed API Proxy** mode (the primary reaches out to the remote's API URL) or **Pilot Agent** mode (the remote dials an outbound tunnel to the primary, so no inbound port is needed on the remote). The checks below cover Proxy mode; if the node is a Pilot Agent, see [Pilot Agent troubleshooting](/features/pilot-agent#troubleshooting) for the tunnel-specific causes (expired enrollment token, agent container not running, blocked outbound HTTPS).
|
||||
|
||||
**Checks in order (Distributed API Proxy mode):**
|
||||
|
||||
1. **Is the remote Sencho instance running?** SSH to that machine and verify.
|
||||
2. **Is the API URL correct?** It must include the protocol and port (e.g. `http://192.168.1.20:3001`). Open it in a browser; you should see a JSON response from `/api/health`.
|
||||
3. **Is the token correct?** Tokens are long JWT strings. Even one missing character will cause auth to fail. Regenerate the token on the remote instance and update the node config.
|
||||
3. **Is the token correct?** Tokens are long JWT strings. Even one missing character will cause auth to fail. Regenerating the token on the remote instance invalidates the previous one, so update the saved node config with the new value.
|
||||
4. **Is there a firewall blocking the port?** The primary Sencho host must be able to reach the remote host's Sencho port.
|
||||
|
||||
To re-test connectivity after making changes, open **Profile > Settings > Nodes** and click the **wifi icon** on the node row.
|
||||
To re-test connectivity after making changes, open **Settings · Infrastructure · Nodes** and click **Test Connection** on the node row. See the [Multi-Node Management troubleshooting section](/features/multi-node#troubleshooting) for additional connectivity scenarios.
|
||||
|
||||
---
|
||||
|
||||
@@ -232,8 +234,7 @@ To re-test connectivity after making changes, open **Profile > Settings > Nodes*
|
||||
|
||||
1. **Is your primary instance licensed?** Open **Settings → Admiral Account** on the primary instance and verify it shows an active Admiral license. Remote nodes inherit the primary's tier; if the primary is on Community, all remote nodes will be Community too.
|
||||
2. **Is the remote node's token valid?** An expired or revoked token prevents the license tier from being transmitted. Regenerate the token on the remote instance and update the node config on the primary.
|
||||
3. **Is the remote node running an up-to-date version of Sencho?** Distributed license enforcement requires both the primary and remote instances to be on a compatible version. Update the remote node if it's outdated.
|
||||
4. **Are you accessing the remote node directly?** If you navigate directly to the remote Sencho instance's URL (bypassing the primary), it uses its own local license. License inheritance only works through the primary's proxy.
|
||||
3. **Are you accessing the remote node directly?** If you navigate directly to the remote Sencho instance's URL (bypassing the primary), it uses its own local license. License inheritance only works through the primary's proxy.
|
||||
|
||||
---
|
||||
|
||||
@@ -263,12 +264,9 @@ To re-test connectivity after making changes, open **Profile > Settings > Nodes*
|
||||
|
||||
**Symptom:** A stack appears in the sidebar with no status indicator (shown as "--"), but clicking on it reveals running containers with active stats.
|
||||
|
||||
**Cause:** The sidebar status check matches containers by their Docker Compose project label. A mismatch can happen when:
|
||||
**Cause:** The sidebar status check matches containers by their Docker Compose project label. A mismatch can happen when the compose file declares a top-level `name:` field that overrides the default project name.
|
||||
|
||||
- The compose file declares a top-level `name:` field that overrides the default project name.
|
||||
- Containers were created before Sencho reorganized compose files into subdirectories, so their labels still reference the old layout.
|
||||
|
||||
**Fix:** Update to the latest version of Sencho. The status check uses multiple fallback strategies (project name mapping, service name, and config file paths) to match containers regardless of how they were originally started.
|
||||
**Fix:** The status check uses multiple fallback strategies (project name mapping, service name, and config file paths) to match containers regardless of how they were originally started, so this usually resolves itself on the next status refresh. If it persists, confirm the containers are actually part of this stack's compose project with `docker compose -f /path/to/your/stack/compose.yaml ps`.
|
||||
|
||||
---
|
||||
|
||||
@@ -280,7 +278,7 @@ To re-test connectivity after making changes, open **Profile > Settings > Nodes*
|
||||
|
||||
- Names must be non-empty and cannot contain only whitespace.
|
||||
- Allowed characters: letters, numbers, hyphens (`-`), underscores (`_`), and dots (`.`).
|
||||
- Names must start with a letter, number, or underscore. They cannot start with a dot or hyphen.
|
||||
- Names must start with a letter or number. They cannot start with a dot, hyphen, or underscore.
|
||||
|
||||
| Name | Valid? | Reason |
|
||||
|------|--------|--------|
|
||||
@@ -288,6 +286,7 @@ To re-test connectivity after making changes, open **Profile > Settings > Nodes*
|
||||
| `app_net.v2` | Yes | |
|
||||
| `.hidden` | No | Cannot start with a dot |
|
||||
| `-leading` | No | Cannot start with a hyphen |
|
||||
| `_leading` | No | Cannot start with an underscore |
|
||||
| `my network` | No | Spaces not allowed |
|
||||
| `net/work` | No | Slashes not allowed |
|
||||
|
||||
@@ -366,7 +365,7 @@ volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
```
|
||||
|
||||
Nodes running very old Sencho versions that predate the capability system need to be updated manually first. After that, future updates can be triggered from the dashboard.
|
||||
After adding the mount and redeploying the remote, it advertises the capability and future updates can be triggered from the dashboard.
|
||||
|
||||
---
|
||||
|
||||
@@ -406,7 +405,7 @@ docker compose pull && docker compose up -d
|
||||
|
||||
1. **Immediate failure:** The gateway could not reach the remote node's update endpoint, or the remote node rejected the request. Common reasons include network issues, expired API tokens, or the remote node not supporting self-update.
|
||||
|
||||
2. **Delayed failure (after ~90 seconds):** The update was accepted by the remote node, but the node never restarted. This usually means the image pull failed on the remote host. The error message will read: *"Update may have failed. The node is still running and its version has not changed."*
|
||||
2. **Delayed failure (after ~3 minutes):** The update was accepted by the remote node, but the node never restarted. This usually means the image pull failed on the remote host. The error message will read: *"Update may have failed. The node is still running and its version has not changed."*
|
||||
|
||||
**Fix:**
|
||||
|
||||
@@ -456,35 +455,18 @@ After adding the missing volume mount, restart Sencho and retry the update.
|
||||
|
||||
---
|
||||
|
||||
## First remote update always times out on old nodes
|
||||
|
||||
**Symptom:** After triggering a remote update on a node running a very old Sencho version (pre-v0.39.3), the node successfully restarts with the new version, but the dashboard shows **Timed out** or **Failed** instead of **Updated**.
|
||||
|
||||
**Cause:** The gateway detects update completion using three signals: a version change, a process restart (via `startedAt`), or temporary offline detection. Nodes running Sencho versions older than v0.39.3 report their version as `"unknown"` and do not include `startedAt` in their metadata. If the container restart is brief enough that the gateway does not detect the node going offline, none of the three signals fire.
|
||||
|
||||
**Fix:** This only affects the **first** update from a very old version. After the update completes (even though the dashboard may show "Failed" or "Timed out"), the remote node will be running the latest version with proper version reporting and restart detection. Future updates triggered from the dashboard will complete normally.
|
||||
|
||||
1. Click **Dismiss** on the badge to clear the state.
|
||||
2. Click **Recheck** to verify the node is now running the latest version.
|
||||
3. If the node still shows "unknown", update it manually on the remote host:
|
||||
|
||||
```bash
|
||||
docker compose pull && docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Remote node version shows "unknown"
|
||||
|
||||
**Symptom:** A remote node appears online in the Fleet View but its version badge is missing or the Node Updates modal shows "unknown" in the current version column.
|
||||
|
||||
**Common causes:**
|
||||
|
||||
1. **Network issue:** The gateway cannot reach the remote node's `/api/meta` endpoint. Check that the API URL configured for the node is correct and accessible from the gateway host.
|
||||
2. **Old Sencho version:** Nodes running Sencho versions older than v0.39.0 do not report a version in their metadata. Update the remote node manually to resolve this.
|
||||
3. **Development build:** If running from source, ensure you have run `npm install` in the backend directory so the `predev` hook regenerates the version file.
|
||||
1. **Network issue:** The gateway cannot reach the remote node's `/api/meta` endpoint within its 5-second timeout. Check that the API URL configured for the node is correct and accessible from the gateway host.
|
||||
2. **Development build:** If running from source, ensure you have run `npm install` in the backend directory so the `predev` hook regenerates the version file.
|
||||
|
||||
**To verify:** Open your browser's developer tools and check the response from `GET /api/fleet/update-status`. Each node's `version` field should contain a semver string (e.g., `"0.39.4"`). If it shows `null`, the gateway could not determine the remote's version.
|
||||
If a triggered update never resolves once the underlying cause above is fixed, click **Dismiss** on the badge to clear the stuck state, then **Recheck** to re-scan the fleet.
|
||||
|
||||
**To verify:** Open your browser's developer tools and check the response from `GET /api/fleet/update-status`. Each node's `version` field should contain a semver string (e.g., `"0.96.0"`). If it shows `null`, the gateway could not determine the remote's version.
|
||||
|
||||
---
|
||||
|
||||
@@ -494,7 +476,7 @@ docker compose pull && docker compose up -d
|
||||
|
||||
**Checks:**
|
||||
|
||||
1. **At least one label must exist**: Labels are managed in **Profile > Settings > Labels**. Create at least one label before assigning it to stacks.
|
||||
1. **At least one label must exist**: Labels are managed in **Settings · Organization · Labels**. Create at least one label before assigning it to stacks.
|
||||
2. **Assignments are saved**: Open the stack's context menu, choose **Labels**, and confirm the label is checked. Pills appear in the sidebar once at least one label is assigned.
|
||||
|
||||
---
|
||||
@@ -506,7 +488,7 @@ docker compose pull && docker compose up -d
|
||||
**Checks:**
|
||||
|
||||
1. **Stack name match**: The stack name in the routing rule must match exactly. Stack names are case-sensitive and correspond to the directory name in your compose folder.
|
||||
2. **Rule is enabled**: Check that the route's toggle is turned on in **Profile > Settings > Notifications > Notification Routing**.
|
||||
2. **Rule is enabled**: Check that the route's toggle is turned on in **Settings · Notifications · Notification Routing**.
|
||||
|
||||
---
|
||||
|
||||
@@ -522,7 +504,7 @@ docker compose pull && docker compose up -d
|
||||
|
||||
**Symptom:** LDAP connection test fails with a TLS/certificate error.
|
||||
|
||||
**Fix:** If your LDAP server uses a self-signed certificate, toggle off "Verify TLS certificate" in **Profile > Settings > SSO**. For production, install a trusted certificate instead.
|
||||
**Fix:** If your LDAP server uses a self-signed certificate, toggle off "Verify TLS certificate" in **Settings · SSO**. For production, install a trusted certificate instead.
|
||||
|
||||
---
|
||||
|
||||
@@ -544,7 +526,7 @@ docker compose pull && docker compose up -d
|
||||
|
||||
**Cause:** SSO providers only appear on the login page when they are both **configured** (saved with valid credentials) and **enabled** (toggle is on).
|
||||
|
||||
**Fix:** Open **Profile > Settings > SSO** and verify the provider has an **Active** badge and its toggle is enabled.
|
||||
**Fix:** Open **Settings · SSO** and verify the provider has an **Active** badge and its toggle is enabled.
|
||||
|
||||
---
|
||||
|
||||
@@ -607,13 +589,6 @@ The backend logs all route errors and service failures to stdout. This is the fi
|
||||
|
||||
**Symptom:** The **From Docker Run** tab in the Create Stack dialog returns an error toast saying the command could not be parsed.
|
||||
|
||||
**Cause:** The input is not a well-formed `docker run` command, or it uses a flag the converter does not recognize.
|
||||
**Cause:** The input is not a well-formed `docker run` command, uses a flag the converter does not recognize, or exceeds the length limit.
|
||||
|
||||
**Fix:**
|
||||
|
||||
- Make sure the command starts with `docker run` and ends with an image reference (e.g. `nginx:alpine`).
|
||||
- Check the [list of supported flags](/features/stack-management#supported-flags). Rare flags (such as `--userns` or custom runtime options) are not recognized. Remove the flag before converting and add it back manually in the editor afterwards.
|
||||
- Collapse multi-line commands into a single line. Mixed quoting across `\`-continued lines is a common source of parse errors.
|
||||
- Commands longer than 8192 characters are rejected. Trim anything non-essential and run the converter on the reduced command.
|
||||
|
||||
When only part of a command is supported, convert what you can, paste the resulting YAML into the **Empty** tab as a starting point, and hand-edit the rest in `compose.yaml`.
|
||||
See [Convert from a docker run command](/features/stack-management#convert-from-a-docker-run-command) for the full list of supported flags and every rejection cause, including the exact size limit and the fix for quoting issues in multi-line commands.
|
||||
|
||||
@@ -32,6 +32,16 @@ After confirming:
|
||||
|
||||
Tell the user to re-enrol from **Settings · Account · Two-factor authentication · Set up 2FA** as soon as they are back in. The account is unprotected until they do.
|
||||
|
||||
<Warning>
|
||||
The shield icon is not hidden on your own row. If you use it on yourself, it signs you out immediately, the same as it does for any other user, and you sign back in with your password alone. If you still have a working authenticator or a backup code, disabling from **Settings · Account · Two-factor authentication** instead keeps your session alive, since that flow proves possession first and reseals your session under the new token version.
|
||||
</Warning>
|
||||
|
||||
## Lockout after failed attempts
|
||||
|
||||
A reset is also the fix for a user locked out by repeated bad codes, not just a lost authenticator. Five wrong TOTP or backup-code submissions in a row during sign-in lock the account for 15 minutes. The lockout blocks further sign-in attempts only; any session the user already has open keeps working.
|
||||
|
||||
Waiting out the 15 minutes clears the lockout on its own. If the user needs back in sooner, or you are not sure whether they are locked out or genuinely lost their authenticator, an administrator reset from **Settings · Users** clears both: it removes the enrolment entirely, which also drops any in-progress lockout.
|
||||
|
||||
## Emergency recovery from the command line
|
||||
|
||||
If every administrator has lost access to 2FA and no one can sign in through the UI, reset the admin account directly on the host running Sencho.
|
||||
|
||||
+12
-10
@@ -24,10 +24,14 @@ docker stop sencho && docker rm sencho
|
||||
# Re-run your original docker run command
|
||||
```
|
||||
|
||||
Sencho will apply any necessary database migrations automatically on startup. No manual steps are required.
|
||||
<Tip>
|
||||
Sencho is also mirrored on GitHub Container Registry at `ghcr.io/studio-saelix/sencho:latest` with the same tags and digests as Docker Hub. Pull from whichever registry your environment prefers.
|
||||
</Tip>
|
||||
|
||||
Sencho applies any necessary database migrations automatically on startup. No manual steps are required.
|
||||
|
||||
<Note>
|
||||
Remote nodes can be updated directly from the Fleet View without dropping to a shell. See [Remote Updates](/features/remote-updates) for details.
|
||||
Remote nodes can be updated directly from the Fleet View without dropping to a shell. See [Remote Updates](/features/remote-updates) for details. Admiral **Hardened Build** installs use a different, entitlement-gated update path instead of the manual steps above; see [Updating the local (gateway) node](/features/remote-updates#updating-the-local-gateway-node) for that flow.
|
||||
</Note>
|
||||
|
||||
---
|
||||
@@ -37,11 +41,11 @@ Sencho will apply any necessary database migrations automatically on startup. No
|
||||
Sencho handles all schema changes internally. When the application starts, it checks whether the database needs updating and applies any pending migrations automatically. This covers:
|
||||
|
||||
- **New tables and columns** for features introduced in newer versions
|
||||
- **Legacy config migration** from very early versions that used a JSON config file
|
||||
- **Admin account migration** from single-admin storage to the multi-user system
|
||||
- **Encryption of sensitive values** (node API tokens, registry credentials) that were previously stored in plaintext
|
||||
- **Config import** from an on-disk JSON config file, if one exists from a manual setup
|
||||
- **Admin account consolidation** into the multi-user system
|
||||
- **Encryption of node API tokens** stored in plaintext (registry credentials are always stored encrypted, so they need no migration)
|
||||
- **SSO and RBAC setup** for single sign-on provider config and role-based access
|
||||
- **Legacy cleanup** of obsolete fields from pre-0.7 versions (SSH/TLS columns)
|
||||
- **Obsolete column cleanup**, removing unused SSH/TLS configuration columns no longer read or written by the current schema
|
||||
- **Blueprint rollout approval** columns (`approval_status`, intent fingerprint, and blast JSON). Existing Blueprints start **pending**. Automatic reconciliation and enforcement pause until an admin opens **Apply now**, reviews the rollout preview, and confirms. New installs behave the same way for each Blueprint until the first confirmation.
|
||||
|
||||
You never need to run SQL commands, migration scripts, or any manual database operations.
|
||||
@@ -67,12 +71,10 @@ See the [Backup & Restore guide](/operations/backup) for full backup procedures.
|
||||
If you prefer to control exactly which version you run, pin the image tag in your `docker-compose.yml`:
|
||||
|
||||
```yaml
|
||||
image: saelix/sencho:0.38.0
|
||||
image: saelix/sencho:0.96.0
|
||||
```
|
||||
|
||||
|
||||
|
||||
Fleet can update semver pins directly from the Node updates sheet: it rewrites the tag to the selected release before recreating the container. Digest pins and compose values that use variable interpolation must be changed manually before Fleet can update the node.
|
||||
Fleet can update semver pins directly from the [Node updates](/features/remote-updates) sheet: it rewrites the tag to the selected release before recreating the container. Digest pins and compose values that use variable interpolation must be changed manually before Fleet can update the node.
|
||||
|
||||
Check [GitHub Releases](https://github.com/studio-saelix/sencho/releases) for available versions and changelogs.
|
||||
|
||||
|
||||
@@ -131,6 +131,19 @@ Each release publishes two moving tags plus one immutable tag, so you can choose
|
||||
|
||||
For production, pin to `X.Y.Z` or `X.Y` and verify the signature on every pull. For staging or development, `latest` is fine.
|
||||
|
||||
### Integration tag (post-merge, pre-release)
|
||||
|
||||
Every push to `main` publishes the current integration build so you can pull and smoke-test the exact code queued for the next release before it is ever tagged. This tag is GHCR-only, published to a separate package from the release image, and carries no signature, SBOM, or VEX attestation.
|
||||
|
||||
| Tag | Example | Updates on |
|
||||
|---|---|---|
|
||||
| `dev` | `ghcr.io/studio-saelix/sencho-dev:dev` | Every push to `main` |
|
||||
| `dev-<sha>` | `ghcr.io/studio-saelix/sencho-dev:dev-a1b2c3d` | Never (immutable per build) |
|
||||
|
||||
<Note>
|
||||
The `:dev` image is not for production. It is unsigned, is never published to Docker Hub, and does not carry the SBOM, provenance, or VEX attestations described above.
|
||||
</Note>
|
||||
|
||||
### Preview tags (pre-merge only)
|
||||
|
||||
Maintainers publish these from open PRs for external validation. They are unsigned and not for production.
|
||||
|
||||
Reference in New Issue
Block a user