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
7dde257e1fab84bbfcafbcd78ec2ba4597781398
sencho/docs/features/resources.mdx
T
Anso 49d775c61f feat(volumes): add read-only volume browser (#926) 
* feat(volumes): add read-only volume browser

Adds a browser for the contents of any Docker named volume. Click the
folder icon on a volume row (admin only) to open a sheet with a directory
tree on the left and a file viewer on the right.

Backend
-------
New VolumeBrowserService spawns a one-shot Alpine 3.20 helper container
with the target volume mounted read-only at /v. The container runs as
nobody (65534:65534) with a read-only rootfs, no network, all caps
dropped, no-new-privileges, and capped at 64 PIDs and 128 MiB. The
helper image is pulled on first use per node.

Listing and stat use a portable busybox-compatible shell loop (find
-printf is not available on Alpine). Reads use head -c with an
explicit -- separator; the helper's working directory is /v so user
paths are passed as ./<path> argv elements and never as flags. The
container lifecycle is managed manually (create, attach, start, wait,
remove) to avoid the AutoRemove race where dockerode sees a 404 on
its post-exit container lookup.

Path safety: relative paths are sanitized server-side, rejecting
parent-escape segments, absolute paths, null bytes, and oversized
input. Symlinks are listed but never followed on read. Files larger
than 5 MB are truncated; binary content is detected via null-byte
scan and returned base64-encoded. Non-zero helper exits map to
404, 403, or 500 by classifying stderr.

Routes mounted at /api/volumes:
- GET /:name/list?path=
- GET /:name/stat?path=
- GET /:name/read?path=

All three require admin. The read endpoint always inserts an audit
log row (success or failure) with the actual response status code,
volume name, and relative path.

Frontend
--------
FileTree generalized to take a loadDir callback and a sourceKey
instead of a hard-coded stackName. The single existing consumer
(StackFileExplorer) was updated and its tests rewritten. The loader
is read through a ref so re-creating the arrow on every parent
render does not re-trigger the root fetch effect.

New VolumeBrowserSheet renders the tree against the volume API,
shows file content (hex view for binaries), and surfaces truncation.
Rapid sheet open and reopen on different volumes is generation-
checked to avoid stomping the visible result with a stale read.

A persistent footnote reminds the user that file reads are recorded
in the audit log, and the docs page warns about the typical contents
of database volumes.

Tests
-----
15 new vitest cases cover the pure helpers (path traversal, volume
name validation, binary detection). The Docker-facing exec path is
exercised by manual end-to-end via curl against a seeded volume.

* fix(volumes): truncate long volume names in browser sheet header

Wide volume names overlapped the close X. Reserve right padding on
the header, set min-w-0 on the flex title, mark the icon and refresh
button shrink-0, and truncate the name span.

* fix(volumes): satisfy lint on volume browser additions

prefer-const on sanitizeRelPath's local; drop unused FileTree entry
arg from the file-select callback (variance lets the arrow take fewer
params than the contract).
2026-05-05 00:09:40 -04:00

172 lines
8.6 KiB
Plaintext
Raw Blame History

---
title: Resources Hub
description: Browse, filter, and clean up Docker images, volumes, networks, and unmanaged containers.
---
The **Resources** tab gives you a full view of everything Docker is storing on your host, broken down by type and ownership.
<Frame>
<img src="/images/resources/resources-reclaim.png" alt="Resources Hub with reclaim hero, disk footprint treemap, and quick clean panel" />
</Frame>
## Reclaim hero
When there is reclaimable disk space (unused images, stopped containers, or dangling volumes), an amber banner leads the view with the total amount you can free and a breakdown of what contributes to it. Click **Review & prune** to jump straight into a confirmation dialog scoped to every reclaimable resource at once.
The hero stays hidden when there is nothing to reclaim, keeping the view focused on the rest of your inventory.
## Docker disk footprint
Below the hero, a three-tile treemap shows how your Docker disk usage is distributed:
| Segment | Meaning |
|---------|---------|
| **Sencho Managed** (green) | Images and volumes used by stacks in your `COMPOSE_DIR` |
| **External** (amber) | Images and volumes used by Docker projects outside Sencho |
| **Reclaimable** (neutral) | Unused images, stopped containers, and dangling volumes safe to delete |
Tile area is proportional to bytes. Click any tile to filter the tabs below to that category.
## Quick Clean panel
Four prune buttons let you reclaim disk space immediately. By default they operate on **Sencho-managed resources only**, so they will not touch external Docker projects.
| Button | What it removes |
|--------|----------------|
| **Prune Unused Images** | Images with no running containers in Sencho stacks |
| **Prune Unused Volumes** | Volumes not attached to any Sencho container |
| **Prune Dead Networks** | Networks not connected to any Sencho container |
| **Purge Unmanaged Containers** | Containers Sencho doesn't recognize (started outside it) |
The first three buttons have a **More options** dropdown that lets you target **all Docker resources** instead of Sencho-only. Use this carefully, as it can affect other Compose projects running on the same host. The "Purge Unmanaged Containers" button always targets unmanaged containers only.
A confirmation dialog appears before any destructive operation, showing a summary of what will be removed. While the operation runs, a loading notification appears so you know Sencho is working. Once complete, a success or error notification replaces it with details on how much space was reclaimed.
## Resource tabs
### Images
Lists all Docker images on the host with their ID, repository tag, size, and status.
**Filter buttons:** `All` / `Managed` / `External`
**Status badges:**
- `In Use` + stack name - image is actively used by a running container in a Sencho-managed stack
- `In Use` + `External` - image is used by a container outside Sencho
- `Unused` - image has no running containers; safe to delete
Click the trash icon on any row to delete an individual image. Sencho will warn you if the image is in use.
#### Inspect image
Click the eye icon on any image row to open a detail panel showing:
- **Overview** - ID, size, creation date, architecture and OS, author, and all repository tags
- **Config** - Default `Cmd`, `Entrypoint`, `WorkingDir`, `User`, exposed ports, environment variables, and labels (env and labels are collapsible)
- **Layers** - Ordered layer history. Each row shows layer index, size, age, and the build command (`CreatedBy`). Empty layers (metadata-only, zero bytes) are dimmed.
The inspect panel is read-only and available to all users.
### Volumes
Lists all Docker volumes. Columns: name, driver, mount point, size, and managed status.
When any volumes are present, a two-card landing strip above the table highlights the **Largest 5** volumes by size and **Recently changed** volumes from the last 24 hours. This makes it easy to spot growing volumes or newly created data at a glance.
**Filter buttons:** `All` / `Managed` / `External`
<Warning>
Deleting a volume is permanent. Any data stored in it will be lost. Always back up important volume data before pruning.
</Warning>
#### Browse volume contents
Click the folder icon on any volume row (admin only) to open a read-only browser for that volume. The panel shows a directory tree on the left and a file viewer on the right.
- **Read only.** No edits, no writes, no deletions. The browser launches a short-lived helper container with the volume mounted read-only.
- **Size cap.** Files are read up to 5 MB. Larger files show a truncation banner.
- **Binary files** are displayed as a hex view. Plain text is shown directly.
- **Symlinks** are listed but never followed. Reading a symlink path returns an error.
- **Audit log.** Every file read is recorded in the audit log, including failed reads, with the volume and path. Use this for compliance and incident review.
<Warning>
Volumes commonly contain database files, password hashes, certificates, and other secrets. Treat the volume browser as a high-power admin tool.
</Warning>
### Networks
Lists all Docker networks. Columns: ID, name, driver, scope (`local`, `global`, `swarm`), and managed status.
**Filter buttons:** `All` / `Managed` / `External`
System networks (like `bridge`, `host`, `none`) are shown but cannot be deleted.
<Frame>
<img src="/images/networks/networks-list.png" alt="Networks list view with filter, inspect, and create actions" />
</Frame>
#### Create network
Click **+ Create Network** (admin only) to open the creation dialog.
<Frame>
<img src="/images/networks/create-network.png" alt="Create Network dialog with name, driver, subnet, and gateway fields" />
</Frame>
| Field | Required | Description |
|-------|----------|-------------|
| **Name** | Yes | Alphanumeric, hyphens, underscores, and dots |
| **Driver** | No | `bridge` (default), `overlay`, `macvlan`, `host`, or `none` |
| **Subnet** | No | CIDR notation, e.g. `172.20.0.0/16` |
| **Gateway** | No | Gateway IP, e.g. `172.20.0.1` |
| **Internal** | No | Isolates the network from external access |
| **Attachable** | No | Allows containers to be manually attached |
#### Inspect network
Click the eye icon on any network row to open a detail panel showing:
- **Overview** - ID, driver, scope, creation date, internal/attachable flags
- **IPAM configuration** - Subnet, gateway, and IP range
- **Options** - Driver-specific options applied to the network (when present)
- **Connected containers** - Container name, IPv4 address, and MAC address
- **Labels** - All Docker labels applied to the network
<Frame>
<img src="/images/networks/network-inspect.png" alt="Network inspect panel showing IPAM config and connected containers" />
</Frame>
#### Network topology <span style={{fontSize: '0.75em', color: 'var(--brand)'}}>Skipper</span>
Switch to the **Topology** view to see an interactive graph of your Docker networks and the containers connected to them. The graph uses automatic hierarchical layout (networks on top, containers below) that scales cleanly regardless of how many networks and containers you have.
<Frame>
<img src="/images/networks/network-topology.png" alt="Network topology visualization showing containers connected to networks" />
</Frame>
- **Network nodes** - Dashed border cards showing network name and driver, color-coded by status (managed, external, system)
- **Container nodes** - Cards showing container name, state indicator, stack badge, image name, and IP addresses per network
- **Edges** - Animated color-coded connections between networks and their containers
- **Click-to-logs** - Click any running container node to open its log viewer directly
- **Refresh** - Use the refresh button in the toolbar to re-fetch the topology on demand
- Pan, zoom, and drag nodes to explore the topology
- A mini map in the bottom-right provides an overview
##### Show system networks
By default, system networks (`bridge`, `host`, `none`) are hidden. Toggle **Show system networks** to include them in the graph, which is useful for debugging containers attached to the default bridge network.
<Frame>
<img src="/images/networks/network-topology-toggle.png" alt="Network topology with system networks visible" />
</Frame>
<Note>
Network Topology requires a Skipper or Admiral license. Community users see an upgrade prompt.
</Note>
### Unmanaged
Lists containers running on the host that are not part of any Sencho-managed stack. This includes containers started with `docker run`, or Compose projects outside your `COMPOSE_DIR`.
This view is useful for identifying orphaned containers after a failed deployment or after moving stacks in and out of `COMPOSE_DIR`. A badge on the tab shows the count of unmanaged containers when any are detected.
Reference in New Issue View Git Blame Copy Permalink