mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-08-20 23:32:19 +00:00
docs: v1 docs refresh (#966)
* docs(introduction): rewrite intro page and refresh screenshots
Rewrite the Getting Started introduction to reflect the current product:
adds the Mesh, Blueprints, Pilot, Fleet, Resources concepts up front;
restructures capability sections around Stacks, Fleet (now including
Fleet Actions), Mesh, Blueprints, Monitoring, Resources, Security,
Automation, and Pilot/Remote ops; cross-links every claim to the
matching feature page.
Replaces the dashboard hero shot with a fresh capture against the
redesigned cockpit chrome and adds three inline shots (running stack
with anatomy and logs, fleet command deck, resources hub with
reclaim header). All screenshots taken at 1920x900, dark theme,
with node names, usernames, IPs, and home paths neutralized.
Drops outdated claims: stale "190+ templates" count, the
"viewer accounts" RBAC summary, and the "atomic" deployment label
that did not match the actual rollback mechanism.
* docs(introduction): add Federation and Fleet Secrets
Federation has shipped (Admiral) with cordon and pin policy as
operator overrides on the blueprint reconciler. Fleet Secrets is
landing as a Skipper+ tab for versioned env-var bundles encrypted
at rest, with diff preview and target push.
Mirror those in the Run-one-machine-or-many bullet list and in the
Tiers paragraph so the introduction matches the current product.
* docs(introduction): re-shoot screenshots against v0.72.0 production
Re-capture all four introduction screenshots from the upgraded
production node so the fleet view shows the current full tab strip
(Overview / Snapshots / Status / Deployments / Traffic / Federation
/ Fleet Actions / Secrets) instead of the older Overview / Snapshots
/ Status only. Same 1920x900 dark-theme capture and the same PII
scrub applied (node names, usernames, IPs, home paths neutralized).
* docs(quickstart): rewrite around v0.72.0 cockpit and add screenshots
Replaces the bare install snippet with a five-minute walkthrough that
matches the redesigned UI. Leads with a docker-compose.yml block (the
bare docker run command is collapsed in an Accordion), keeps the 1:1
path rule, and adds two new sections that show the user what happens
on first boot.
Adds two screenshots at 1920x900 dark theme:
- setup-cold-start.png: the Cold start card with Username, Password,
Confirm password fields, and the Initialize console button.
- dashboard.png: the post-sign-in dashboard captured against v0.72.0
with the full top nav (Home, Fleet, Resources, App Store, Logs,
Auto-Update, Console, Audit, Schedules) and the populated Stack
health table sorted by load.
Where-to-next now uses CardGroup cols=2 to match the introduction
page's pattern.
* docs(configuration): align env var reference with current backend
Bring docs/getting-started/configuration.mdx up to date with the
v0.72.0 backend:
- Remove PORT from the optional env vars table. The listen port is
hardcoded to 1852 in backend/src/helpers/constants.ts and is never
read from the environment. Replace it with a Listen port section
that explains the fixed port and host-port remapping.
- Document API_RATE_LIMIT (default 200) and API_POLLING_RATE_LIMIT
(default 300), both applied in production only.
- Note the /app/compose fallback default for COMPOSE_DIR while still
pointing readers at the 1:1 path rule.
- Point the SSO env var section at the new SSO Quickstart page and
keep the SSO feature reference as the deeper dive.
- Tighten First boot and cross-link to Quickstart so the screenshot
is not duplicated.
- Add a Where to next CardGroup matching the refreshed Introduction
and Quickstart pages.
Drop stale PORT=1852 and JWT_SECRET=your-secure-jwt-secret-here
lines from .env.example so the example no longer contradicts the
docs (PORT is hardcoded, JWT_SECRET is auto-generated and persisted
to the database during initial setup).
* docs(configuration): replace em-dash-substitute hyphens in prose
Three sentences used ` - ` (space-hyphen-space) as an em-dash
substitute. Replaced with the punctuation that fits each case:
- "How Sencho organizes your compose directory": semicolon between
the two related clauses.
- Data directory Warning: parentheses around the parenthetical
insertion.
- 1:1 path rule explanation: comma before the contrastive clause.
Heading slugs and YAML code-block comments are unchanged.
* docs(sso): refresh setup guide and drop misleading "one-click" wording
Brings the SSO Setup Guide in line with how SSO actually works in the
current build, and corrects misleading copy across both SSO docs pages.
- Setup Guide: explains the env-var-seeds-once / DB-is-authoritative
config model up front, replacing per-section "Restart Sencho"
wording that implied a restart was always required.
- Setup Guide: promotes the per-provider Test Connection button out
of the LDAP-only paragraph into a generic intro callout, and adds
a self-signed LDAPS tip.
- Setup Guide: notes that all OIDC providers accept a *_DISPLAY_NAME
override for the login button label, and adds a commented LDAP TLS
toggle to the full compose example.
- Setup Guide: adds two screenshots of the redesigned Settings > SSO
panel (overview + LDAP card expanded with form).
- Both pages: replaces "one-click presets" / "one-click configuration"
with "preset providers". The Skipper-tier presets still require an
OAuth app provisioned in the provider's console; what they actually
buy is provider-aware defaults and a branded login button. The old
wording overpromised.
* docs(features-overview): regroup catalog and add 17 missing features
Restructure the Features Overview into the same six groups the docs
sidebar uses (Stacks & Deployments, Observability, Fleet & Multi-Node,
Security & Identity, Automation, Platform) plus a short Reference tail.
Add catalog entries for 17 shipped features that the previous overview
never mentioned: Stack Activity, Stack File Explorer, Deploy Progress,
Deploy Enforcement, Blueprints, Git Sources, Global Search, Pilot Agent,
Sencho Mesh, Fleet Federation, Fleet Actions, Fleet Sync, Fleet Secrets,
Two-Factor Authentication, CVE Suppressions, Auto-Heal Policies, Stack
Sidebar.
Fix two factual inaccuracies:
- Fleet View blurb wrongly gated search, sort, filter, and stack
drill-down behind Skipper. The deep-dive is explicit that those are
available on every tier; only the bulk Update All action inside the
Node Updates modal is paid.
- Auto-update entry was titled and described as a scheduling system.
The deep-dive page is the Auto-Update Readiness board (risk tags,
changelog previews, rollback targets); the scheduler lives under
Scheduled Operations.
Add three hero screenshots captured from production at 1920x900,
illustrating the redesigned cockpit visual language: Home dashboard,
stack anatomy, and fleet topology.
* docs(stack-management): refresh page around v0.72.0 cockpit and add screenshots
Updates the Stack Management page to match the current UI: sidebar with
filter chips and label groups, bulk mode, restructured kebab menu,
two-tab anatomy panel, and three-source New stack dialog (Empty, From
Git, From Docker Run).
Adds sections for Filter chips, Pinned and label groups, and Bulk mode.
Restructures the Stack context menu around the inspect, organize,
lifecycle, and destructive groups with their keyboard shortcuts.
Documents the From Git tab and cross-links Git Sources for the full
sync flow.
Replaces every existing screenshot with fresh captures from the current
UI and adds eight new captures for the new sections. Cross-links Stack
Activity, Stack Labels, Stack File Explorer, Compose Editor, Atomic
Deployments, Scheduled Operations, Auto-Heal Policies, Auto-Update
Policies, and Alerts and Notifications for features documented on
their own pages.
* docs(stack-activity): refresh page around v1 cockpit and recapture screenshots
Realign the page with the current Anatomy panel tab strip and the
StackActivityTimeline component:
- Frame the Activity tab as a sibling of Anatomy under the right-hand
panel, with files/edit actions belonging to the strip.
- Expand the category guidance: list the five iconized categories and
call out that other stack-scoped notifications (deploy failure,
available image updates, auto-heal triggers, monitor alerts, scan
findings) flow into the timeline with a generic icon.
- Tighten the actor-attribution rule to match the component: omitted
for events without an actor and for system-driven events.
- Add the day-format example to the relative-time row.
- Recapture both screenshots from a populated stack (Today + Yesterday
+ Earlier with three distinct icons) and an empty stack.
- Convert troubleshooting blurbs to H3 for anchor links and consistency
with the v1-refresh sibling pages.
* docs(stack-activity): wrap troubleshooting entries in Accordion blocks
Match the foldable troubleshooting pattern established by
docs/features/deploy-progress.mdx so the page stays compact and
readers can scan to their issue. This is the canonical formatting
for the /features section's troubleshooting blurbs going forward.
* docs(editor): refresh page around v1 cockpit and recapture screenshots
Rewrites the page around the dual-mode right panel (Anatomy by default,
Monaco when the user clicks edit), the redesigned Command Center action
bar, the new container row layout with status badges and live stats, the
Structured / Raw terminal logs toggle, the Git Source toolbar button, and
the opt-in diff preview. Drops the obsolete persistent embedded terminal
section. Preserves the #diff-preview-before-save and #log-viewer anchors
referenced from settings.mdx and global-observability.mdx. Replaces
editor-overview.png and container-exec-modal.png with fresh captures
against v0.72.0 production at 1920x900 dark theme; renames container
-actions.png to containers-list.png; adds command-center.png and
editor-edit-mode.png. PII scrubbed (host paths normalized) and the
compose-diff-preview/diff-modal.png shared asset is left untouched after
visual diff against the live UI showed no chrome change.
* docs(features): wrap troubleshooting accordions in AccordionGroup
Wraps the loose <Accordion> blocks in editor.mdx and stack-activity.mdx
in a single <AccordionGroup> to match the troubleshooting design used
by fleet-federation.mdx. Structural only; no content changes.
* docs(stack-file-explorer): refresh page around v1 explorer and add screenshots
Full rewrite to match the live two-pane Files tab. Replaces the false
'Edit' toolbar flow with the read-only chip + always-on Save model,
fixes the protected-files list (5 names) and dedicated-tab redirect
list (3 names), drops the fabricated 100 MB download cap, and corrects
the upload claim to single file at a time.
Adds sections for New File, Rename, Permissions, the type-to-confirm
protected-file delete flow, the non-empty folder delete confirmation,
the 500-entry tree display cap, and the symlink rendering. Restructures
troubleshooting around <AccordionGroup> + <Accordion> to match
fleet-federation.mdx, and adds two new entries (display cap, 403 on
Community admin write).
Ships nine screenshots captured against v0.72.0 production at 1920x900
in dark theme: overview, two-pane layout, protected-tree-marker,
viewer-edit-mode, new-file-dialog, context-menu-folder, context-menu-file,
permissions-dialog, delete-protected-confirm.
* docs(deploy-progress): rewrite around current modal + capture v1 screenshots
Aligns the page with the v0.72.0 implementation and standardizes the
troubleshooting layout with the rest of the docs refresh.
Setting and gating
- Renames the Settings field to "Deploy progress modal" and quotes the
current helper text verbatim. Documents that the toggle is off by
default, lives under Settings > Appearance > Display, is stored in
localStorage, and syncs across tabs in the same browser.
Modal anatomy
- Names every visible UI string: header verbs, status indicator (with
the "closes in <n>s" countdown that was previously undocumented),
empty-body strings, footer toggle that flips between "Raw output" and
"Hide raw", and the destructive border on ERR rows vs the softer warn
tint on WARN rows.
- Replaces the vague "after a few seconds" with the actual 4-second
auto-close timer; documents hover-to-pause and the
leave-hover-restarts-the-countdown behavior.
- Documents the truncated error message in the failed-state header and
the manual close-only requirement.
- Notes that the pill is portal-mounted and survives navigation.
Stage badges
- Keeps the 9-badge table but adds an honest note that most lines render
as LOG because the badges are gated on Compose's "[+]" progress
prefix, which Compose only emits in TTY mode and Sencho spawns it
without one.
Entry points
- Splits the supported actions into the four that produce a populated
structured-log body (Deploy, Update, Install, Git Apply) and the two
that bypass compose and finish with 0 lines (Restart, Stop). Drops the
"Down" claim from the user-facing list since no UI control currently
triggers it; mentions the down route as an automation surface only.
Troubleshooting
- Wraps the existing accordions in an <AccordionGroup> matching the
pattern used by the editor and stack-activity refreshes. Adds two new
entries: one explaining the Restart/Stop "0 lines" outcome, one
explaining the LOG-everywhere case for non-TTY compose output.
Screenshots (six PNGs in docs/images/deploy-progress/, 1920x900, dark
theme, captured against the upgraded production node)
- setting-toggle.png: the Display section with the toggle enabled.
- modal-streaming.png: a real update in flight at 19s, 554 lines.
- modal-succeeded.png: succeeded state with the live closes-in
countdown visible.
- modal-raw-output.png: structured rows with the Raw output panel
expanded beneath.
- pill.png: minimized pill anchored bottom-center on a stack editor
view.
- modal-failed.png: failed state with the truncated error in the
header and ERR rows highlighted.
* docs(resources): refresh Resources Hub page for v1 redesign and feature additions
Rewrite the page to match the shipping UI and replace stale screenshots
with fresh captures of the redesigned chrome.
- Document the admin-only Reclaim hero and clarify the per-tile Sencho-only
vs. All Docker (includes external) split in Quick Clean.
- Add coverage of the Scan history toolbar button and the per-row severity
badge plus shield-icon scan dropdown in the Images tab; cross-link to the
vulnerability scanning page.
- Correct the Volumes column list (no Size column; size lives on the Largest
5 landing card) and call out admin gates on browse and delete.
- Spell out the List/Topology view-mode toggle and that Create Network is
admin-only and List-mode only.
- Rewrite the Unmanaged tab section around the project-grouped layout, the
Select all + Purge Selected (N) admin-only multi-select, and the empty
state copy.
- Replace screenshots: resources-reclaim, networks-list, create-network,
network-inspect, network-topology, network-topology-toggle. Add fresh
resources-volumes-tab and resources-unmanaged-tab captures.
* docs(app-store): refresh page around v1 deploy sheet, scan integration, and registry settings
Rewrites the App Store reference to match the current cockpit:
- Documents the weekly-rotated featured banner picked from the top-5 by GitHub stars and the star-descending grid sort.
- Adds the deploy-sheet structure (breadcrumb, meta line, About panel with Read more) and splits the Advanced tab into Ports, Volumes, Environment variables, Custom variables, and Security subsections.
- Documents the Trivy-gated Security checkbox, atomic vs non-atomic deploys by tier, and the rollback semantics driven by error class.
- Adds a Watching the deploy section linking to the deploy-progress modal.
- Rewrites the Custom registry section against the new two-panel settings layout (Default + Custom) with the URL validation rule and the using default / using custom hint.
- Adds a four-entry Accordion troubleshooting block in the house style.
- Replaces three screenshots and adds two (Advanced tab, Settings registry panel) captured against the production node.
Permissions wording aligns with current backend (admin only); the broader stack:create gate will land in a follow-up fix branch.
* docs(app-store): describe inline port-conflict messaging on deploy sheet
Update the deploy-sheet section to match the visible port-conflict
behavior: the Essentials tab surfaces a Port-conflict warning that
replaces the defaults hint when any default port is already bound, and
the Advanced tab shows an inline "in use by {stack}" message next to
the container port instead of a hover-only tooltip. Refresh the
screenshot alt-text and the troubleshooting Accordion to match.
* docs(app-store): align permissions note with stack:create gate
Pairs with the backend gate swap in fix/templates-deploy-rbac (#986)
which moves POST /api/templates/deploy from requireAdmin to
requirePermission('stack:create'). Updates the Note block under
'Watching the deploy' so the docs match the new behavior: admin and
node-admin can deploy templates from the App Store; viewer, deployer,
and auditor cannot.
This commit is contained in:
Anso
@@ -9,7 +9,7 @@ Sencho is configured entirely through environment variables and Docker volume mo
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `COMPOSE_DIR` | Absolute path to the directory that contains your Compose stacks. Every subdirectory inside becomes a stack in Sencho. |
|
||||
| `COMPOSE_DIR` | Absolute path to the directory that contains your Compose stacks. Every subdirectory inside becomes a stack in Sencho. Falls back to `/app/compose` if unset, but per the [1:1 path rule](#compose-directory-the-11-path-rule) you should always set this explicitly to match the host path you mount. |
|
||||
|
||||
<Note>
|
||||
**JWT_SECRET is generated automatically.** Sencho creates a secure random signing key during initial setup and stores it in its database. You do not need to provide one.
|
||||
@@ -17,17 +17,29 @@ Sencho is configured entirely through environment variables and Docker volume mo
|
||||
|
||||
### How Sencho organizes your compose directory
|
||||
|
||||
When you point `COMPOSE_DIR` at a directory, Sencho expects each stack to live in its own subdirectory. If you create a stack through the UI, Sencho automatically creates a subfolder and places a blank `compose.yaml` inside it. Sencho does not move or "capture" existing files - it simply treats every subdirectory as a separate stack.
|
||||
When you point `COMPOSE_DIR` at a directory, Sencho expects each stack to live in its own subdirectory. If you create a stack through the UI, Sencho automatically creates a subfolder and places a blank `compose.yaml` inside it. Sencho does not move or "capture" existing files; it simply treats every subdirectory as a separate stack.
|
||||
|
||||
## Optional environment variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `PORT` | `1852` | Port the Sencho HTTP server listens on. |
|
||||
| `DATA_DIR` | `/app/data` | Directory where Sencho stores its SQLite database, node registry, and cached metrics. |
|
||||
| `FRONTEND_URL` | *(empty)* | Frontend origin for CORS. Only needed if the UI is served from a different domain than the API. Leave empty for same-origin setups. |
|
||||
| `NODE_ENV` | `production` | Set automatically in the Docker image. Only change this for local development. |
|
||||
| `SENCHO_USER` | *(unset)* | Optional. When set to a username present inside the container (`sencho` is pre-created for this purpose), the entrypoint drops privileges to that user at startup instead of running as `root`. See [Running as a non-root user](#running-as-a-non-root-user) below. |
|
||||
| `SENCHO_USER` | *(unset)* | When set to a username present inside the container (`sencho` is pre-created for this purpose), the entrypoint drops privileges to that user at startup instead of running as `root`. See [Running as a non-root user](#running-as-a-non-root-user) below. |
|
||||
| `API_RATE_LIMIT` | `200` | Global API requests per minute per user session. Applies in production only; development uses a fixed higher cap. Authenticated requests are keyed by user ID, unauthenticated by IP. Internal node-to-node traffic bypasses this limit. |
|
||||
| `API_POLLING_RATE_LIMIT` | `300` | Rate limit for dashboard polling endpoints, in requests per minute. Applies in production only; development uses a fixed higher cap. Raise it for environments with many concurrent browser sessions behind shared NAT. |
|
||||
|
||||
## Listen port
|
||||
|
||||
Sencho always listens on `1852` inside the container. The port is fixed and is not read from an environment variable. To expose Sencho on a different host port, remap with Docker's `-p` flag (or the `ports:` key in your compose file):
|
||||
|
||||
```yaml
|
||||
ports:
|
||||
- "8080:1852" # host 8080 to container 1852
|
||||
```
|
||||
|
||||
Behind a reverse proxy you can keep the standard mapping and let the proxy own the public port.
|
||||
|
||||
## Container user
|
||||
|
||||
@@ -71,7 +83,7 @@ If you use SSO (Admiral), configure your identity providers via environment vari
|
||||
| `SSO_OIDC_OKTA_ENABLED` | Enable Okta SSO |
|
||||
| `SSO_CALLBACK_URL` | External base URL for OAuth callbacks (required behind reverse proxy) |
|
||||
|
||||
For the full SSO configuration reference and setup guides, see [SSO Authentication →](/features/sso).
|
||||
For end-to-end provider setup walkthroughs, see the [SSO Quickstart →](/getting-started/sso-quickstart). For the full feature reference, see [SSO Authentication →](/features/sso).
|
||||
|
||||
## Required volume mounts
|
||||
|
||||
@@ -94,7 +106,7 @@ volumes:
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Without a persistent data mount, Sencho will lose all configuration - including registered nodes, alerts, and settings - every time the container restarts.
|
||||
Without a persistent data mount, Sencho will lose all configuration (including registered nodes, alerts, and settings) every time the container restarts.
|
||||
</Warning>
|
||||
|
||||
### Compose directory - the 1:1 path rule
|
||||
@@ -103,7 +115,7 @@ volumes:
|
||||
This is the most common source of deployment problems. Read carefully.
|
||||
</Warning>
|
||||
|
||||
When Sencho runs `docker compose up`, it does so on your **host machine**. Docker resolves relative volume paths in your Compose files relative to the **host** path of the stack directory - not the path inside the Sencho container.
|
||||
When Sencho runs `docker compose up`, it does so on your **host machine**. Docker resolves relative volume paths in your Compose files relative to the **host** path of the stack directory, not the path inside the Sencho container.
|
||||
|
||||
**The rule:** Mount your Compose directory at the **exact same path** inside the container as it exists on your host.
|
||||
|
||||
@@ -270,4 +282,21 @@ Caddy automatically obtains and renews SSL certificates via Let's Encrypt. WebSo
|
||||
|
||||
## First boot
|
||||
|
||||
After starting Sencho, open it in your browser. If no admin account exists yet, you'll be taken to a setup screen to create one. This only appears once - subsequent visits go directly to the login page.
|
||||
After starting Sencho, open `http://localhost:1852` in a browser. On a fresh install you land on the **Cold start** card to create the first admin account; every subsequent visit goes to the regular sign-in screen. The [Quickstart](/getting-started/quickstart#first-boot) shows it in detail.
|
||||
|
||||
## Where to next
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Stack management" icon="layer-group" href="/features/stack-management">
|
||||
Deploy, edit, restart, update, and roll back stacks from the cockpit.
|
||||
</Card>
|
||||
<Card title="Multi-node" icon="sitemap" href="/features/multi-node">
|
||||
Add a remote Sencho instance and manage it from the same console.
|
||||
</Card>
|
||||
<Card title="Self-hosting" icon="server" href="/operations/self-hosting">
|
||||
Resource recommendations, networking, and Docker socket security.
|
||||
</Card>
|
||||
<Card title="SSO Quickstart" icon="key" href="/getting-started/sso-quickstart">
|
||||
End-to-end provider setup for OIDC, LDAP, and Active Directory.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@@ -3,56 +3,120 @@ title: Introduction
|
||||
description: What Sencho is and why you might want it.
|
||||
---
|
||||
|
||||
Sencho is a self-hosted Docker Compose management dashboard. It gives you a clean web UI to deploy, manage, and monitor your Docker Compose stacks - locally or across multiple remote servers - without touching a terminal.
|
||||
Sencho is a self-hosted Docker Compose dashboard. It puts a cockpit on top of one Docker host or a fleet of them, so you can deploy stacks, watch them run, and intervene when something goes sideways without leaving the browser.
|
||||
|
||||
There is no SSH and no remote Docker socket. Every node is a Sencho instance talking to its own local Docker, and Sencho-to-Sencho calls go over plain HTTP with a token.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/dashboard/dashboard-overview.png" alt="Sencho dashboard showing system stats and container metrics" />
|
||||
<img src="/images/dashboard/dashboard-overview.png" alt="Sencho cockpit dashboard with status masthead, system gauges, and stack health table" />
|
||||
</Frame>
|
||||
|
||||
## Key concepts
|
||||
|
||||
- **Stacks** - a Docker Compose project living in your `COMPOSE_DIR`. Sencho treats each subdirectory as a stack.
|
||||
- **Nodes** - a Sencho instance. Your local machine is always the default node. Add remote nodes by pointing Sencho at another Sencho instance's API URL.
|
||||
- **Resources** - images, volumes, and networks that belong to your stacks (managed) or exist outside them (external/unused).
|
||||
A few words show up everywhere in Sencho. Knowing them up front makes the rest of the docs (and the UI) easier to read.
|
||||
|
||||
- **Stack** is one Compose project: a directory under `COMPOSE_DIR` with a `compose.yaml` and friends. Each subdirectory is one stack.
|
||||
- **Node** is a Sencho instance. The local node is always present. Remote nodes are added by their Sencho URL plus an API token; Sencho never reaches into them with SSH or a remote Docker socket.
|
||||
- **Fleet** is the set of nodes you manage from one console.
|
||||
- **Resources** are the images, volumes, and networks Docker accumulates, classified as managed (created by a stack), external (attached but not owned), or unused (safe to prune).
|
||||
- **Blueprint** is a declarative spec for one or more stacks, applied across selected nodes by a reconciler that converges drift back to the spec.
|
||||
- **Mesh** is a managed sidecar overlay that gives stacks stable service discovery to each other across nodes.
|
||||
- **Pilot** is an outbound agent that lets a node be managed by the console without exposing an inbound port.
|
||||
|
||||
<Note>
|
||||
Sencho never accesses remote servers directly via SSH or Docker TCP. Remote management works by proxying API requests to another running Sencho instance.
|
||||
Remote management is HTTP between Sencho instances. Each remote runs the same Sencho binary against its own local Docker; the console only proxies requests with a long-lived token.
|
||||
</Note>
|
||||
|
||||
## What you can do
|
||||
|
||||
### Stack lifecycle
|
||||
- **Deploy and control stacks** - create, start, stop, restart, update, roll back, and delete Compose stacks with one click
|
||||
- **Edit files in-browser** - full Monaco editor for `compose.yaml` and `.env` files with syntax highlighting, save-and-deploy in one step
|
||||
- **Atomic deployments** - automatic backup and rollback on every deploy. If containers crash, the previous configuration is restored automatically
|
||||
- **Stack labels** - organize stacks with custom labels for quick filtering and grouping
|
||||
### Run stacks like a cockpit, not a pile of YAML
|
||||
|
||||
### Monitoring & observability
|
||||
- **Real-time dashboard** - live CPU, RAM, disk, and network stats with 24-hour historical charts
|
||||
- **Global log aggregation** - stream logs from all containers across all stacks in a single view, with filtering by stack, level, and keyword search
|
||||
- **Alerts & notifications** - threshold-based alerts (CPU, memory, network, restart count) routed to Discord, Slack, or any webhook endpoint
|
||||
- **Notification routing** - fine-grained control over which alerts go to which channels
|
||||
- **Audit log** - searchable trail of every mutating action with timestamps, user attribution, and node context
|
||||
A selected stack opens with its container, live metrics, full log stream, anatomy panel (entrypoints, mounts, networks), and a row of actions across the top.
|
||||
|
||||
### Infrastructure
|
||||
- **Multi-node management** - add remote Sencho instances as nodes and manage them identically to your local machine
|
||||
- **Fleet view** - monitor your entire infrastructure from a single screen with health metrics, container counts, and resource usage
|
||||
- **Fleet-wide backups** - point-in-time snapshots of every compose and env file across all nodes, with per-stack restore
|
||||
- **Remote updates** - check for and apply Sencho updates across your fleet from the dashboard
|
||||
<Frame>
|
||||
<img src="/images/introduction/stack-view.png" alt="Plex stack open in Sencho with running container, anatomy panel, and live log stream" />
|
||||
</Frame>
|
||||
|
||||
### Resources & registry
|
||||
- **Resource hub** - browse, filter, and prune Docker images, volumes, and networks with managed/external/unused classification
|
||||
- **App Store** - deploy from 190+ pre-configured application templates with category filtering and one-click setup
|
||||
- **Private registries** - store credentials for Docker Hub, GHCR, AWS ECR, or self-hosted registries with automatic injection during deploys
|
||||
- Deploy, start, stop, restart, update, and roll back from one bar of buttons. See [Stack management](/features/stack-management).
|
||||
- Edit `compose.yaml` and `.env` in a built-in [Monaco editor](/features/editor) with syntax highlighting and save-and-deploy in one step.
|
||||
- Browse the on-disk files of a stack, including bind mounts, with the [stack file explorer](/features/stack-file-explorer).
|
||||
- Every deploy snapshots the prior configuration and rolls back automatically if the new containers fail to come up. See [atomic deployments](/features/atomic-deployments) for the exact behavior.
|
||||
- Organize at scale with [stack labels](/features/stack-labels) and filter chips in the [sidebar](/features/sidebar). Paste any `docker run` command into the create-stack flow and it converts to a Compose stack.
|
||||
|
||||
### Automation & integration
|
||||
- **Webhooks** - trigger stack actions from CI/CD pipelines via HTTP with HMAC-SHA256 authentication
|
||||
- **Scheduled operations** - run stack actions on a cron schedule directly from the UI
|
||||
- **Auto-update policies** - configure automatic image update checks and apply updates on your terms
|
||||
- **API tokens** - create scoped tokens for programmatic access and external integrations
|
||||
### Run one machine or many
|
||||
|
||||
### Administration
|
||||
- **RBAC** - create viewer accounts with read-only access while keeping deploy and edit permissions locked to admins
|
||||
- **SSO** - authenticate via external identity providers
|
||||
- **Host console** - interactive terminal on the host OS directly in the browser; no SSH required
|
||||
- **Docker Run converter** - paste any `docker run` command and convert it to a Compose stack
|
||||
Add a remote Sencho instance by URL and token and it becomes another node in the same surface. The fleet view holds the whole picture: status masthead, per-node CPU / RAM / disk, container counts, and version drift.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/introduction/fleet-overview.png" alt="Sencho fleet view with three node cards and per-node metrics" />
|
||||
</Frame>
|
||||
|
||||
- [Fleet view](/features/fleet-view) and [multi-node management](/features/multi-node) cover the basics: search, sort, expand, drill in.
|
||||
- [Fleet snapshots](/features/fleet-backups) (a.k.a. Sencho Cloud Backup) take point-in-time copies of every `compose.yaml` and `.env` across the fleet, with per-stack restore.
|
||||
- [Remote updates](/features/remote-updates) check the Sencho version on every node and apply per-node updates from the console.
|
||||
- [Fleet Actions](/features/fleet-actions) bundles fleet-wide bulk operations: stop every stack with a given label across the fleet, or apply a label set to many stacks on one node in a single round trip.
|
||||
- [Federation](/features/fleet-federation) gives the operator explicit overrides on top of the blueprint reconciler: cordon a node out of rotation, pin a stack to a host, hold ground while you investigate.
|
||||
- [Fleet Secrets](/features/fleet-secrets) stores versioned env-var bundles encrypted at rest and pushes them to selected stacks on selected nodes with a diff preview before any write.
|
||||
|
||||
### Mesh
|
||||
|
||||
Stacks on different nodes need to call each other often enough that doing it by hand is tedious and error-prone. [Sencho Mesh](/features/sencho-mesh) plants a managed sidecar in opted-in stacks and gives services stable hostnames across the fleet, with an activity stream you can watch in real time.
|
||||
|
||||
### Blueprints
|
||||
|
||||
[Blueprints](/features/blueprint-model) describe one or more stacks declaratively and apply them to selected nodes through a reconciler. The reconciler captures a compose snapshot before any stateful eviction, so reapplying a Blueprint is safe even when it replaces an existing stack.
|
||||
|
||||
### Monitoring and observability
|
||||
|
||||
- The [dashboard](/features/dashboard) hits you with a status line, a unified gauge strip, a stack-health table sorted by load, and a fleet heartbeat.
|
||||
- [Global observability](/features/global-observability) streams logs from every container on every node into one searchable view.
|
||||
- [Alerts](/features/alerts-notifications) on CPU, memory, disk, restart count, and similar thresholds, [routed](/features/notification-routing) to Discord, Slack, or any webhook by rules.
|
||||
- [Audit log](/features/audit-log) keeps a searchable trail of every mutating action with actor and node attribution.
|
||||
|
||||
### Resources you can actually clean up
|
||||
|
||||
The Resources hub treats images, volumes, and networks as a single inventory, classified as managed, external, or unused, with a "you can reclaim X" header so it is obvious what cleanup is worth doing.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/introduction/resources-hub.png" alt="Sencho Resources hub showing reclaimable disk space and image inventory with severity badges" />
|
||||
</Frame>
|
||||
|
||||
See [Resources](/features/resources) for the full hub, the [App Store](/features/app-store) for a library of one-click templates, and [private registries](/features/private-registries) for credential storage that injects automatically at deploy time.
|
||||
|
||||
### Security and identity
|
||||
|
||||
- [RBAC](/features/rbac) with five roles (admin, viewer, deployer, node admin, auditor) and per-capability scoped permissions.
|
||||
- [SSO](/features/sso) with custom OIDC, one-click presets for common providers, and LDAP / Active Directory.
|
||||
- [Two-factor authentication](/features/two-factor-authentication) with TOTP and backup codes.
|
||||
- [Vulnerability scanning](/features/vulnerability-scanning) via Trivy with [CVE suppressions](/features/cve-suppressions) and [deploy-blocking scan policies](/features/deploy-enforcement) on paid tiers.
|
||||
- [Image signature verification](/operations/verifying-images) for cosign-signed releases.
|
||||
|
||||
### Automation and integration
|
||||
|
||||
- [Webhooks](/features/webhooks) trigger stack actions from CI / CD with HMAC-SHA256 signatures.
|
||||
- [API tokens](/features/api-tokens) cover programmatic access for scripts and external tools.
|
||||
- [Scheduled operations](/features/scheduled-operations) run deploys, restarts, scans, and snapshots on cron.
|
||||
- [Auto-update policies](/features/auto-update-policies) check registries on a schedule and apply updates only on the rules you set.
|
||||
- [Auto-heal policies](/features/auto-heal-policies) restart containers that stay in an unhealthy Docker healthcheck state past a threshold, with cooldown and per-hour caps.
|
||||
|
||||
### Pilot and remote ops
|
||||
|
||||
Some nodes can't accept an inbound connection (CG-NAT, locked-down VLAN, no public IP). The [Pilot agent](/features/pilot-agent) opens an outbound tunnel to the console node so it can be managed without exposing a port. When you are already on a node and want to drop into a shell, the [host console](/features/host-console) gives you an interactive terminal in the browser.
|
||||
|
||||
## Tiers at a glance
|
||||
|
||||
Sencho ships in three tiers: **Community**, **Skipper**, and **Admiral**. Community covers single- and multi-node deploy, monitor, and security basics. Skipper adds automation, fleet secrets, and advanced fleet management. Admiral covers enterprise-grade controls (audit log, host console, cross-node Mesh traffic management, federation overrides, fleet-wide policy push). The full matrix lives on the [licensing page](/features/licensing).
|
||||
|
||||
## Where to next
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Quickstart" icon="rocket" href="/getting-started/quickstart">
|
||||
Install Sencho, deploy a first stack, add a node.
|
||||
</Card>
|
||||
<Card title="Configuration" icon="sliders" href="/getting-started/configuration">
|
||||
Environment variables, compose dir, and core settings.
|
||||
</Card>
|
||||
<Card title="Self-hosting" icon="server" href="/operations/self-hosting">
|
||||
Reverse proxy, TLS, backups, and production patterns.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@@ -3,16 +3,46 @@ title: Quickstart
|
||||
description: Get Sencho running in under five minutes.
|
||||
---
|
||||
|
||||
This walks you from a clean Docker host to a working Sencho cockpit. Five minutes if your Compose directory is already in the right place, ten if you need to lay it out first.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Docker and Docker Compose installed on the host
|
||||
- A directory where your Compose projects live (e.g. `/opt/compose`)
|
||||
- Docker and Docker Compose installed on the host.
|
||||
- A directory where your Compose projects live (for example `/opt/compose`). Each subdirectory inside becomes one stack in Sencho.
|
||||
|
||||
## Run with Docker
|
||||
## Run with Docker Compose
|
||||
|
||||
Drop this into a `docker-compose.yml` next to your Compose tree (or anywhere convenient) and bring it up:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
sencho:
|
||||
image: saelix/sencho:latest
|
||||
container_name: sencho
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "1852:1852"
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
- /opt/compose:/opt/compose # 1:1 path rule, see below
|
||||
- sencho_data:/app/data
|
||||
environment:
|
||||
- COMPOSE_DIR=/opt/compose
|
||||
|
||||
volumes:
|
||||
sencho_data:
|
||||
```
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
<Accordion title="Prefer docker run?">
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name sencho \
|
||||
--restart unless-stopped \
|
||||
-p 1852:1852 \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||
-v /opt/compose:/opt/compose \
|
||||
@@ -21,24 +51,63 @@ docker run -d \
|
||||
saelix/sencho:latest
|
||||
```
|
||||
|
||||
Open `http://localhost:1852` in your browser. On first boot you'll be prompted to create an admin account.
|
||||
|
||||
<Note>
|
||||
Replace `/opt/compose` with the path to your Compose projects directory. Every subdirectory inside it becomes a stack in Sencho. A `JWT_SECRET` is generated automatically on first boot; you do not need to provide one.
|
||||
</Note>
|
||||
</Accordion>
|
||||
|
||||
<Tip>
|
||||
Sencho is also published on GitHub Container Registry at `ghcr.io/studio-saelix/sencho:latest` with the same tags and content as Docker Hub. Pull from whichever registry your environment prefers.
|
||||
Sencho is 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>
|
||||
|
||||
## Important: the 1:1 path rule
|
||||
<Note>
|
||||
`JWT_SECRET` is generated on first boot and persisted to the database. You do not need to provide one.
|
||||
</Note>
|
||||
|
||||
The compose directory must be mounted at the **same path** inside and outside the container. The example above mounts `/opt/compose` to `/opt/compose`, which is correct. If your stacks live at a different path, adjust both sides of the mount to match. See the [Configuration guide](/getting-started/configuration#compose-directory-the-11-path-rule) for details.
|
||||
## The 1:1 path rule
|
||||
|
||||
## Next steps
|
||||
The Compose directory must be mounted at the **same path** inside and outside the container. The example above mounts `/opt/compose` to `/opt/compose`, which is correct. If your stacks live somewhere else, adjust both sides of the mount to match.
|
||||
|
||||
- [Configuration](/getting-started/configuration) - environment variables, volume mounts, reverse proxy setup
|
||||
- [Features Overview](/features/overview) - tour of everything Sencho can do
|
||||
- [Stack Management](/features/stack-management) - create and deploy your first stack
|
||||
- [Multi-Node](/features/multi-node) - add a remote server to manage from this dashboard
|
||||
- [App Store](/features/app-store) - deploy from 190+ pre-configured templates
|
||||
<Warning>
|
||||
This is the most common source of deployment problems. If the host and container paths differ, every relative volume in your Compose files will resolve to the wrong location once Sencho asks Docker to bring a stack up. See the [Configuration guide](/getting-started/configuration#compose-directory-the-11-path-rule) for the full explanation.
|
||||
</Warning>
|
||||
|
||||
## First boot
|
||||
|
||||
Open `http://localhost:1852` in a browser. On a fresh install you land on the **Cold start** card, where Sencho asks you to create the first admin account.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/quickstart/setup-cold-start.png" alt="Sencho first-boot Cold start card with Username, Password, and Confirm password fields, and an Initialize console button" />
|
||||
</Frame>
|
||||
|
||||
Pick a username (the placeholder shows `admin`), choose a password, confirm it, and click **Initialize console**. The strength indicator under the password field expects at least eight characters.
|
||||
|
||||
<Note>
|
||||
The Cold start card only appears the first time you open Sencho. Once the admin account exists, every subsequent visit goes to the regular sign-in screen.
|
||||
</Note>
|
||||
|
||||
## After signing in
|
||||
|
||||
You land on the dashboard. A status bar across the top tells you whether the fleet is healthy, the gauge strip below it shows CPU, memory, disk, and network at a glance, and the **Stack health** table sorts your stacks by load.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/quickstart/dashboard.png" alt="Sencho dashboard with status bar across the top, CPU/MEMORY/DISK/NETWORK gauges, and a Stack health table sorted by load" />
|
||||
</Frame>
|
||||
|
||||
The top nav (HOME, FLEET, RESOURCES, APP STORE, LOGS, AUTO-UPDATE, CONSOLE, AUDIT, SCHEDULES) is your map of the cockpit. The sidebar on the left lists every stack Sencho discovered under `COMPOSE_DIR`; on a fresh install it is empty until you create one.
|
||||
|
||||
Click **Create Stack** in the sidebar to deploy your first stack, or open **App Store** in the top nav for a one-click template.
|
||||
|
||||
## Where to next
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Configuration" icon="sliders" href="/getting-started/configuration">
|
||||
Environment variables, volume mounts, reverse proxy, and the 1:1 path rule in detail.
|
||||
</Card>
|
||||
<Card title="Stack management" icon="layer-group" href="/features/stack-management">
|
||||
Deploy, edit, restart, update, and roll back stacks from the cockpit.
|
||||
</Card>
|
||||
<Card title="Multi-node" icon="server" href="/features/multi-node">
|
||||
Add a remote Sencho instance and manage it from the same console.
|
||||
</Card>
|
||||
<Card title="App Store" icon="grid-2" href="/features/app-store">
|
||||
Browse 190+ pre-configured templates and deploy in one click.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@@ -3,12 +3,25 @@ title: SSO Setup Guide
|
||||
description: Step-by-step instructions for connecting Sencho to your identity provider.
|
||||
---
|
||||
|
||||
SSO can be configured via environment variables (shown below) or from the Settings UI after first boot.
|
||||
SSO can be configured from the Settings UI or seeded via environment variables (shown below).
|
||||
|
||||
<Note>
|
||||
**Tier availability.** Custom OIDC is available on every tier, including Community. The Google, GitHub, and Okta one-click presets require Skipper or higher. LDAP / Active Directory requires Admiral. See [Licensing & Billing](/features/licensing#feature-breakdown) for the full breakdown.
|
||||
**Tier availability.** Custom OIDC is available on every tier, including Community. The Google, GitHub, and Okta preset providers require Skipper or higher. LDAP / Active Directory requires Admiral. See [Licensing & Billing](/features/licensing#feature-breakdown) for the full breakdown.
|
||||
</Note>
|
||||
|
||||
<Frame>
|
||||
<img src="/images/sso/sso-quickstart-overview.png" alt="Settings > SSO panel showing all five provider cards with PROVIDERS and ENABLED stats in the masthead" />
|
||||
</Frame>
|
||||
|
||||
## How to configure
|
||||
|
||||
You can wire SSO two ways. Both reach the same database row, and you can mix and match.
|
||||
|
||||
- **Environment variables** seed the SSO configuration the first time Sencho boots with that variable set. They are useful for infrastructure-as-code, fresh deployments, and disaster recovery. After a configuration row exists in the database, the database is authoritative; subsequent restarts do not re-read the env vars or overwrite changes you made in the UI.
|
||||
- **Settings > SSO** in the dashboard lets admins enable, edit, save, and remove providers without restarting. Changes apply immediately. Each provider card has a **Test Connection** button that validates connectivity before you commit (LDAP bind plus search for LDAP, OIDC discovery plus token endpoint reachability for OIDC).
|
||||
|
||||
If you want a guided UI walkthrough rather than the env-var path below, jump to the [SSO feature page](/features/sso#configuration).
|
||||
|
||||
## Google OIDC
|
||||
|
||||
1. Go to the [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
|
||||
@@ -33,7 +46,7 @@ services:
|
||||
- /opt/compose:/opt/compose
|
||||
```
|
||||
|
||||
Restart Sencho. A "Google" button will appear on the login page.
|
||||
A **Google** button appears on the login page after the first boot with these variables set. To override the button label, set `SSO_OIDC_GOOGLE_DISPLAY_NAME` (and the equivalent `_DISPLAY_NAME` variable for any other provider).
|
||||
|
||||
## GitHub OAuth
|
||||
|
||||
@@ -128,12 +141,20 @@ If your provider uses non-standard claim names, add claim mapping:
|
||||
- SSO_LDAP_DEFAULT_ROLE=viewer
|
||||
```
|
||||
|
||||
After starting Sencho, verify the connection in **Settings > SSO** using the **Test Connection** button.
|
||||
Once Sencho is running, open **Settings > SSO**, expand the LDAP card, and click **Test Connection**. Sencho binds with the service account, runs the search filter, and reports the result inline.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/sso/sso-quickstart-ldap-test.png" alt="LDAP provider card expanded showing the configuration form with example values, the Verify TLS certificate toggle, and Save and Test Connection buttons" />
|
||||
</Frame>
|
||||
|
||||
<Warning>
|
||||
If your LDAP server is on the Docker host (not in a container), use the host's LAN IP or `host.docker.internal` (Docker Desktop) instead of `localhost`.
|
||||
</Warning>
|
||||
|
||||
<Tip>
|
||||
For self-signed LDAPS certificates, set `SSO_LDAP_TLS_REJECT_UNAUTHORIZED=false` (or untick **Verify TLS certificate** in the UI). Use only when you control the certificate authority.
|
||||
</Tip>
|
||||
|
||||
## Role mapping
|
||||
|
||||
By default, all SSO users are assigned the **Viewer** role. To grant Admin to specific users:
|
||||
@@ -188,6 +209,7 @@ services:
|
||||
- SSO_LDAP_SEARCH_BASE=ou=users,dc=example,dc=com
|
||||
- SSO_LDAP_SEARCH_FILTER=(sAMAccountName={{username}})
|
||||
- SSO_LDAP_ADMIN_GROUP_DN=cn=sencho-admins,ou=groups,dc=example,dc=com
|
||||
# - SSO_LDAP_TLS_REJECT_UNAUTHORIZED=false # uncomment for self-signed LDAPS
|
||||
# Role mapping & callback
|
||||
- SSO_OIDC_ADMIN_CLAIM=groups
|
||||
- SSO_OIDC_ADMIN_CLAIM_VALUE=sencho-admins
|
||||
|
||||
Reference in New Issue
Block a user