gsadmin/sencho
1
0
Fork 0
mirror of https://github.com/Studio-Saelix/sencho.git synced 2026-07-27 12:18:59 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
v0.83.1
sencho/docs/features/fleet-view.mdx
T
Anso 16774ae515 feat(fleet): add node management actions to Fleet Overview (#1064) 
* refactor(nodes): extract node create/edit/delete modals into useNodeActions hook

Pulls the inline Add/Edit/Delete/Pilot-enrollment modal stack out of
NodeManager.tsx and into a reusable useNodeActions() hook in
components/nodes/. Settings continues to consume the same modals via
this hook, with an onTestResult callback used by Settings to render the
existing connection-detail panel after a successful test.

The hook also extends the auto-test-on-save behavior so that saving a
proxy-mode remote node from the Edit dialog re-runs the connection test
when the API URL or token has actually changed (skipped when only name
or compose dir was edited).

* feat(fleet): surface Add/Edit/Delete node actions on Fleet Overview

Adds an admin-only Add node button to the right of Refresh on the Fleet
header, opening the same Add Node dialog used by Settings. Each node
card's three-dot menu now exposes Edit node and Delete node items
(routed through the shared useNodeActions hook) alongside the existing
Cordon item, so operators can manage node lifecycle without leaving the
Fleet page.

The card kebab is shown to admins regardless of tier; Cordon stays
Admiral-only. Delete is hidden on the local default node. After any
Add/Edit/Delete the Fleet overview refetches so the grid reflects the
change immediately.

* docs(fleet): document Add/Edit/Delete node actions on Fleet Overview

Updates the Action buttons table to cover the new Add node entry point
on the Fleet header, and adds a new Node actions menu section
describing the per-card Edit/Delete/Cordon items, their tier and
permission gating, and the auto connection test that fires after
saving a proxy-mode remote.
2026-05-15 19:54:23 -04:00

304 lines
16 KiB
Plaintext
Raw Permalink Blame History

---
title: Fleet View
description: Monitor all your nodes from a single dashboard with real-time health metrics, search, filtering, and container drill-down.
---
The **Fleet** tab gives you a bird's-eye view of every node in your Sencho deployment, local and remote, on one screen. It is available to all tiers, with advanced features unlocked by Skipper and Admiral.
<Note>
Fleet is hub-only and is hidden from the nav strip when a remote node is the active selection. See [Multi-Node Management](/features/multi-node#what-top-level-views-show-when-a-remote-node-is-active).
</Note>
<Frame>
<img src="/images/fleet-view/fleet-overview.png" alt="Fleet Overview with the fleet masthead, grid/topology toggle, and pinned local node" />
</Frame>
## Page layout
### Fleet masthead
The top of the page is a status masthead that summarises the state of the entire fleet at a glance:
- **Status word** in italic display type: **The fleet** with a pulsing coloured rail (green when all nodes are online and healthy, amber when any node is offline, rose when any node is critical)
- **Meta line** showing node count, online count, and last sync time (e.g. "2 nodes · 1 online · last sync 7s")
- **Reasons** line appears when the fleet is degraded, summarising what's wrong ("1 offline · 1 critical")
- **Stats cluster** with three tiles:
- **CPU**: average across online nodes, with the peak node and percentage called out below
- **MEM**: total RAM used across the fleet, with total capacity and percentage
- **CONTAINERS**: active running count; hover the tile to see a breakdown of running vs total
- **Alerts** indicator on the right shows the current critical count, highlighted in rose when above zero
### Grid / Topology toggle
Below the masthead, switch between two layouts:
- **Grid** (default): one card per node. The local node is pinned at the top with a cyan accent rail and a ★ Local badge so it is never confused with a remote.
- **Topology**: an interactive node-map view. Each node renders as a rack card with a status pill (Online, Critical, or Offline), a Local or Remote badge, CPU, memory, and disk bars, and a stack and running-container summary. Online remotes also show their gateway round-trip latency; cordoned nodes carry an amber **Cordoned** banner; pilot-agent nodes whose heartbeat has gone stale flag a small clock glyph. The local node is framed with a cyan ring. Connector lines colour by link health (cyan when online, amber when critical, dashed when offline). Pan, zoom, and use the minimap to navigate large fleets. Click a node to jump to its details.
<Frame>
<img src="/images/fleet-view/fleet-topology.png" alt="Fleet Topology view showing the local node connected to a remote, each rendered as a rack card with CPU, memory, and disk bars" />
</Frame>
#### Topology layout modes (Skipper+)
A toolbar at the top of the topology canvas offers three layouts. Pick the one that matches how you reason about your fleet.
| Mode | What it does |
|------|--------------|
| **Hub** | Local node on the left; remotes radiate to the right. Best when you have a handful of nodes and want the gateway anchored. |
| **Grouped** | Remotes cluster by their primary node label (alphabetically first when a node has multiple). The local node sits in its own cluster. Use this to read environment, region, or role groupings at a glance. Nodes without any label fall into an Unlabeled cluster. |
| **Free** | Drag any node anywhere on the canvas. Positions persist in this browser, so the arrangement is there when you come back. |
Assign labels in **Settings → Nodes** to drive Grouped mode. Each node accepts multiple labels; the alphabetically first one is its cluster.
### Tabs
The Fleet page has three tabs:
- **Overview**: the monitoring view described on this page
- **Snapshots**: fleet-wide backup snapshots (covered in [Fleet Backups](/features/fleet-backups))
- **Status**: fleet-wide feature status rollup (covered below)
### Action buttons
Three buttons sit in the top-right corner:
| Button | What it does |
|--------|--------------|
| **Check Updates** | Opens the Node Updates modal to view and apply Sencho version updates across your fleet (Skipper+) |
| **Refresh** | Re-fetches data from all nodes. Shows a spinner while loading |
| **Add node** | Opens the same Add Node dialog as Settings → Nodes so you can register a new node without leaving the Fleet page. Admin-only. After saving a remote proxy node, a connection test runs automatically and the result toasts in (success or saved-but-unreachable). |
## Community features
Every Sencho installation gets the full fleet monitoring grid at no cost.
### Node grid
Each node appears as a card showing:
| Data | Description |
|------|-------------|
| **Status badge** | Online (green) or Offline (grayed out) |
| **Type badge** | `local` or `remote` |
| **Version badge** | The node's Sencho version (e.g. `v0.38.0`). Remote nodes running older versions that cannot report their version show no version badge |
| **Update available badge** | Orange pill shown when a newer Sencho version is available for this node |
| **Critical badge** | Red pill shown when CPU or disk usage exceeds 90% |
| **Running containers** | Count of containers in `running` state |
| **Stopped containers** | Count of containers in `exited` state |
| **Stacks** | Total number of Compose stacks on the node |
| **CPU usage** | Current percentage with colour-coded bar (green to amber to red) |
| **RAM usage** | Used / total with percentage bar |
| **Disk usage** | Used / total with percentage bar |
Nodes with an available Sencho update also show an **Update to vX.Y.Z** button at the bottom of the card.
Offline nodes are visually dimmed and show a "Node unreachable" placeholder instead of stats.
### Node actions menu (admin)
The kebab menu in the top-right of each card surfaces the same lifecycle actions you'd find in Settings → Nodes:
| Action | Notes |
|--------|-------|
| **Edit node** | Opens the Edit dialog prefilled with the node's connection details. For proxy-mode remotes, saving with a changed API URL or token re-runs the connection test automatically. |
| **Delete node** | Opens a destructive confirmation. The local (default) node has no Delete option. Deleting a remote only removes it from this console; the remote instance and its containers are untouched. |
| **Cordon node** / **Uncordon node** | Marks the node unschedulable so new blueprint deployments skip it (Admiral). Existing deployments keep running. |
The menu is admin-only. Non-admin users see no kebab on the card.
### Manual refresh
Click the **Refresh** button in the top-right to re-fetch data from all nodes. The button shows a spinner while loading.
---
## Fleet operations
<Note>
The toolbar (search, sort, filters), stack drill-down, auto-refresh, and per-node update flow are available on every tier. The bulk **Update All** action inside the Node Updates modal is a Skipper or Admiral feature.
</Note>
### Auto-refresh
Fleet data automatically refreshes every 30 seconds. A subtle indicator at the bottom of the page confirms this is active. When a node update is in progress, the refresh rate increases to every 5 seconds so you can watch status changes in near real-time.
### Search
The search bar filters the node grid in real time. It matches against:
- Node names (e.g. typing `dev` shows only nodes with "dev" in the name)
- Stack names (e.g. typing `plex` shows only nodes that have a "plex" stack)
### Sorting
Use the sort dropdown to order nodes by:
- **Name** (alphabetical)
- **CPU Usage** (highest first)
- **Memory Usage** (highest first)
- **Containers** (most first)
- **Status** (online first)
Click the arrow button next to the dropdown to toggle ascending/descending.
Sort preferences are saved to your browser and persist across sessions.
### Filtering
Filter pills let you narrow the grid:
| Filter | Options |
|--------|---------|
| **Status** | All, Online, Offline |
| **Type** | All Types, Local, Remote |
| **Critical Only** | Show only nodes with CPU or disk above 90% |
| **Tags** | Filter by stack labels assigned to nodes |
A "Clear filters" button appears when filters hide all nodes.
### Stack drill-down
Click **Stack details** on any online node card to expand the stack list. The button shows the total stack count (e.g. "18 stacks"). Each stack in the list shows a container count badge.
Click a stack name to expand it further and see individual containers with:
- Container name
- State badge (running, exited, restarting)
- Image name (e.g. `linuxserver/plex:latest`)
- Uptime (e.g. "Up 4 days")
Container data is fetched fresh each time you expand a stack, so you always see the current state.
Hover over any container row to reveal an **Open in editor** button that navigates you directly to that stack's editor on the corresponding node.
<Frame>
<img src="/images/fleet-view/fleet-drill-down.png" alt="Fleet View with Stack details expanded showing the stack list and a container drill-down" />
</Frame>
### Critical node detection
Nodes with CPU or disk usage above 90% automatically receive a red **Critical** badge. Combined with the **Critical Only** filter, this lets you quickly triage overloaded servers.
### Node Updates
Click **Check Updates** in the header to open the Node Updates modal. This lets you manage Sencho version updates across your entire fleet from one place.
<Frame>
<img src="/images/fleet-view/fleet-node-updates.png" alt="Node Updates modal showing update status for all fleet nodes" />
</Frame>
The modal shows:
- **Summary cards** at the top: counts of nodes that are Up to date, have updates Available, are currently Updating, or have Failed
- **Latest version** label showing the newest available Sencho release (checked via GitHub Releases, cached for 30 minutes)
- **Filter** search box to find specific nodes
- **Node table** with columns: Node name, Type, Current version, Latest version, and Status (either an "Up to date" badge or an "Update" button)
- **Recheck** button to refresh the latest version from GitHub and re-scan for available updates
- **Update All** button to trigger updates on all remote nodes that have a pending update (Skipper or Admiral)
When you click **Update** on a remote node, Sencho sends the update command to the remote instance. The remote pulls the latest Docker image, then spawns a short-lived helper container that performs the compose recreate. The node restarts with the new version, and the status badge transitions from "Updating" to "Updated" once the gateway detects the version change. The "Updated" badge remains visible for 60 seconds before the node returns to "Up to date".
If you update the local node, a confirmation dialog appears first, then a reconnection overlay shows while your primary instance restarts.
<Note>
Triggering updates (both individual and bulk) requires admin privileges. Users with viewer or operator roles can see update status but cannot initiate updates.
</Note>
**How self-update works:** Each Sencho instance reads its own Docker Compose labels to determine the image name, compose file path, and service name. It pulls the latest image directly, then spawns a helper container that mounts the compose directory from the host and runs `docker compose up --force-recreate`. This approach works regardless of the container's own volume mounts.
---
## Fleet Status tab
The **Status** tab gives you a fleet-wide summary of which automations and security features are active on each node, without having to open each node's settings individually.
<Frame>
<img src="/images/fleet/configuration-tab.png" alt="Fleet Configuration tab showing per-node configuration summaries with one online node and one offline node" />
</Frame>
Each node appears as a card. Online nodes display a compact two-column summary grid:
| Field | What it shows |
|-------|---------------|
| **Agents** | Delivery agents configured on this node |
| **Alert rules** | Number of per-stack alert rules |
| **Auto-heal** | Active auto-heal policies |
| **Webhooks** | Outbound webhook triggers |
| **MFA** | Whether MFA is set up for the admin account |
| **Scanning** | Active vulnerability scan policies |
| **Backup** | Cloud backup provider, or Disabled |
| **Crash detect** | Whether global crash detection is on |
Offline nodes show a muted card with "Node is unreachable. Configuration unavailable." The online/offline badge confirms the node's current reachability at the time of the last fetch.
The tab fetches configuration data from all nodes in parallel. A dead node does not block the others from rendering.
---
## How fleet data is fetched
Fleet View queries all registered nodes in parallel. Each node responds independently; one slow or offline node does not block the others. Local node data comes from the Docker socket and system stats directly. Remote node data is fetched over the Distributed API proxy using each node's Bearer token.
<Note>
Fleet View always runs on your primary (local) Sencho instance. It is never proxied through a remote node.
</Note>
---
## Troubleshooting
### Version shows as "unknown" for a remote node
This means the remote node's `/api/meta` endpoint did not return a valid version. Common causes:
- **Remote node is offline or unreachable.** Check that the node's API URL and token are correct in the node configuration.
- **Remote node is running an older Sencho version** that predates the version reporting feature. Update the remote node manually (pull the latest Docker image and restart the container) to restore version reporting.
Once the remote node is reachable and running a current Sencho version, its version will appear automatically on the next fleet refresh.
### "Update All" says no updates available
The **Update All** button only triggers updates on remote nodes that:
1. Report a valid version lower than the latest available Sencho release
2. Support the self-update capability (requires running in Docker)
If a remote node's version is unresolvable ("unknown"), the **Update** button on its individual card will still be available, but **Update All** requires both versions to be known for a safe comparison.
### Update fails with "no such file or directory"
If a remote node update fails with an error mentioning a compose file path (e.g. "open /path/to/compose.yaml: no such file or directory"), the remote node is running an older Sencho version (prior to v0.42.0) that attempted to access the compose file directly inside the container, where the host path does not exist.
**Resolution:** Update the remote node manually once by SSH-ing into the host and running:
```bash
docker compose pull && docker compose up -d
```
After this one-time manual update, the node will have the fixed self-update mechanism and all future updates can be triggered from Fleet Overview.
### Update shows "Remote node is unreachable"
This means the gateway could not connect to the remote node's `/api/meta` endpoint. Check that:
- The remote node is powered on and running
- The API URL configured for this node is correct and reachable from the gateway
- The network allows traffic between the gateway and remote node on the configured port
- The remote node's Sencho container is healthy (`docker ps` should show it as running)
### Update button returns "Admin access required"
Fleet update operations (individual updates, Update All) require an admin account. If you see a 403 error when clicking **Update**, ask your Sencho administrator to either grant you admin privileges or perform the update on your behalf.
### Free-mode topology positions don't persist
Free mode stores node positions in your browser's local storage. The arrangement is per-browser, not synced across devices or users. If positions reset on reload, common causes are:
- **Browser local storage is disabled** (private/incognito windows, strict tracking-prevention modes). Sencho falls back to in-memory state for the session, but nothing carries over.
- **Storage was cleared** by browser cleanup tools, profile reset, or by manually clearing site data.
- **A different browser or profile** is being used. Each browser keeps its own arrangement.
To verify storage is writable, open DevTools → Application → Local Storage on the Sencho origin and confirm the `sencho-topology-preferences` key exists after switching modes or dragging a node.
### Grouped topology shows everything in one Unlabeled cluster
Grouped mode clusters remote nodes by their primary node label. When no remotes carry any labels, every remote falls into the **Unlabeled** cluster and the canvas looks similar to Hub mode. A hint banner above the canvas points to **Settings → Nodes** where labels are managed. Add at least one label to two or more remotes and reopen the topology to see the clusters split.
Reference in New Issue View Git Blame Copy Permalink