mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-08-11 19:26:56 +00:00
docs: add Tier 2 feature pages
- dashboard: container stats, system stats, historical charts, docker run converter - resources: disk footprint widget, images/volumes/networks/unmanaged tabs, prune scopes - app-store: template grid, category filter, deploy sheet (env vars/volumes/ports), custom registry - global-observability: unified log stream, standard vs SSE mode, filters, capacity limits - host-console: PTY terminal, shell type, security model, common uses - mint.json: add all 5 new pages to Features nav group
This commit is contained in:
SaelixCode
@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
- feat: automated documentation pipeline with Mintlify sync
|
||||
- feat: CI job to auto-refresh doc screenshots on every develop push
|
||||
- docs: bootstrap user-facing documentation from codebase audit — added configuration, stack management, editor, multi-node, and alerts & notifications pages; updated introduction, quickstart, and features overview; restructured mint.json navigation with Getting Started / Features / Reference / Operations groups
|
||||
- docs: add Tier 2 feature pages — dashboard, resources hub, app store, global observability, and host console
|
||||
|
||||
### Fixed
|
||||
- fix(ci): YAML syntax error in update-screenshots `if:` condition (`!` tag and `: ` in plain scalar); wrapped in `${{ }}`
|
||||
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
title: App Store
|
||||
description: Browse and deploy pre-configured application templates in one click.
|
||||
---
|
||||
|
||||
The **App Store** tab lets you browse a curated catalogue of Docker Compose templates and deploy any of them as a new stack with environment-specific configuration — no YAML required.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/app-store/app-store-overview.png" alt="App Store showing a grid of application templates with category filters" />
|
||||
</Frame>
|
||||
|
||||
## Browsing templates
|
||||
|
||||
Templates are loaded from a remote registry (configurable in **Settings → App Store**). The default registry provides 190+ self-hosted application templates.
|
||||
|
||||
**Search:** Type in the search bar to filter templates by name or description in real-time.
|
||||
|
||||
**Categories:** Click any category pill to narrow the list:
|
||||
`Automation` · `Books` · `Development` · `Documentation` · `Downloaders` · `Media` · `Monitoring` · `Networking` · `Other` · `Product`
|
||||
|
||||
Each template card shows:
|
||||
- Application logo
|
||||
- Name and short description
|
||||
- Category tags
|
||||
- Links to the GitHub repo and documentation (where available)
|
||||
|
||||
## Deploying a template
|
||||
|
||||
Click any template card to open the **deployment sheet** on the right side of the screen. Fill in the fields and click **Deploy**.
|
||||
|
||||
### Stack name
|
||||
|
||||
Pre-filled with the template name in lowercase. You can change it — the same [naming rules](/features/stack-management#creating-a-stack) apply (lowercase, hyphens, no spaces).
|
||||
|
||||
### Environment variables
|
||||
|
||||
Each template declares the variables it needs. Sencho pre-fills sensible defaults where available (e.g. `PUID=1000`, `PGID=1000`, `TZ` from your browser locale).
|
||||
|
||||
Edit any value before deploying. You can also click **Custom Env** to add arbitrary key-value pairs not defined by the template.
|
||||
|
||||
### Volumes
|
||||
|
||||
For each container mount point, enter the **host path** where that data should be stored. Suggested defaults (e.g. `./config`, `./data`) are shown as placeholders.
|
||||
|
||||
<Note>
|
||||
Relative paths like `./config` are resolved relative to the stack directory inside your `COMPOSE_DIR`. Absolute paths map directly to the host filesystem.
|
||||
</Note>
|
||||
|
||||
### Ports
|
||||
|
||||
For each exposed port, edit the **host port** (left side). The container port (right side) is fixed by the template and cannot be changed here — edit the compose file after deployment if needed.
|
||||
|
||||
### What happens on Deploy
|
||||
|
||||
1. Sencho creates a new stack directory in `COMPOSE_DIR`
|
||||
2. Writes the generated `compose.yaml` and `.env` file
|
||||
3. Runs `docker compose up -d`
|
||||
4. On success: switches you to the Editor view for that stack
|
||||
5. On failure: rolls back by running `docker compose down` and deleting the stack directory
|
||||
|
||||
A toast notification confirms success or shows the error message.
|
||||
|
||||
## Custom template registry
|
||||
|
||||
By default Sencho uses the LinuxServer.io template registry. To use your own:
|
||||
|
||||
1. Open **Settings → App Store**
|
||||
2. Enter your registry URL (must serve a JSON array of template objects in Portainer v2 format)
|
||||
3. Click **Save**
|
||||
|
||||
To force a refresh of the cached templates, click **Refresh Cache** in the same settings panel.
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
title: Dashboard
|
||||
description: Real-time system stats, historical metrics, and a quick-start converter for your host machine.
|
||||
---
|
||||
|
||||
The **Home** tab is the first thing you see after logging in. It shows a live snapshot of your host's health alongside container activity across all stacks.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/dashboard/dashboard-overview.png" alt="Sencho dashboard showing container stats, system stats, and historical charts" />
|
||||
</Frame>
|
||||
|
||||
## Container stats
|
||||
|
||||
The top row summarises container state at a glance:
|
||||
|
||||
| Card | What it shows |
|
||||
|------|---------------|
|
||||
| **Active Containers** | Running containers — broken down as `N managed · N external` |
|
||||
| **Exited Containers** | Stopped or crashed containers |
|
||||
| **Docker Network** | Current inbound/outbound network throughput across all containers |
|
||||
|
||||
**Managed** means the container belongs to a stack in your `COMPOSE_DIR`. **External** means it exists on the Docker host but was started outside Sencho (e.g. by another Compose project or `docker run`).
|
||||
|
||||
## System stats
|
||||
|
||||
The second row shows host-level resource usage, polled every few seconds:
|
||||
|
||||
| Card | What it shows |
|
||||
|------|---------------|
|
||||
| **Host CPU** | Current CPU usage percentage and core count |
|
||||
| **Host RAM** | Used / total memory in GB and percentage |
|
||||
| **Host Disk** | Used / total disk space for the primary mount point |
|
||||
|
||||
When any value exceeds configured thresholds (set in **Settings → System Limits**), the card changes colour as a visual warning.
|
||||
|
||||
## Historical metrics charts
|
||||
|
||||
Two area charts display time-series data sampled at one-minute intervals, retained for up to 24 hours (configurable in **Settings → Developer**):
|
||||
|
||||
- **Normalized CPU Usage** — total CPU percentage across all managed containers, normalised over all host cores
|
||||
- **Normalized RAM Usage** — total memory allocated by managed containers, in GB
|
||||
|
||||
The x-axis shows time labels. Hover over a data point to see the exact value at that moment.
|
||||
|
||||
<Note>
|
||||
Charts only show data from the moment Sencho started. If you just installed Sencho, they will be mostly empty until metrics accumulate.
|
||||
</Note>
|
||||
|
||||
## Convert `docker run` to Compose
|
||||
|
||||
The bottom panel provides a quick converter: paste any `docker run` command and Sencho transforms it into a valid `docker-compose.yaml` snippet.
|
||||
|
||||
```bash
|
||||
# Example input
|
||||
docker run -d --name myapp -p 8080:80 -e TZ=UTC -v /data:/app/data nginx:latest
|
||||
```
|
||||
|
||||
Click **Convert** and the output YAML appears ready to copy. You can then create a new stack and paste it into the editor.
|
||||
|
||||
This is useful when migrating existing containers to managed Compose stacks without having to write YAML by hand.
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: Global Observability
|
||||
description: A unified, searchable log stream from every container across all your stacks.
|
||||
---
|
||||
|
||||
The **Logs** tab aggregates output from all running containers into a single scrollable view. Instead of tailing logs one container at a time, you see everything in one place — with filtering to focus on what matters.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/global-observability/global-observability-overview.png" alt="Global Observability view showing real-time log lines from multiple containers" />
|
||||
</Frame>
|
||||
|
||||
## Log format
|
||||
|
||||
Each line shows:
|
||||
|
||||
- **Timestamp** — when the log line was emitted
|
||||
- **Stack name** — the Compose stack the container belongs to (colour-coded)
|
||||
- **Container name** — the specific container
|
||||
- **Level** — `INFO`, `WARN`, or `ERROR` (where detectable)
|
||||
- **Message** — the raw log output
|
||||
|
||||
## Streaming modes
|
||||
|
||||
Sencho supports two modes for fetching logs, switchable via the **Developer mode** toggle:
|
||||
|
||||
| Mode | How it works | Best for |
|
||||
|------|-------------|----------|
|
||||
| **Standard** (default) | Polls all containers every N seconds (configurable in Settings → Developer) | General use; lower overhead |
|
||||
| **Developer mode** | Server-Sent Events stream; logs arrive as they are emitted | Debugging; watching a specific event in real-time |
|
||||
|
||||
The default polling interval is 5 seconds. You can change it to 1, 3, 5, or 10 seconds in **Settings → Developer → Global Logs Refresh Rate**.
|
||||
|
||||
## Filtering logs
|
||||
|
||||
Use the controls above the log panel to narrow what you see:
|
||||
|
||||
| Control | What it does |
|
||||
|---------|-------------|
|
||||
| **Stack filter** | Multi-select dropdown — show only logs from chosen stacks |
|
||||
| **Stream** | `ALL` / `STDOUT` / `STDERR` — filter by output stream |
|
||||
| **Search** | Full-text filter on the message field (case-insensitive) |
|
||||
|
||||
Filters combine — you can show only `STDERR` from a specific stack while searching for a keyword.
|
||||
|
||||
## Controls
|
||||
|
||||
| Button | What it does |
|
||||
|--------|-------------|
|
||||
| **Clear** | Clears the current log buffer in the UI (does not delete logs from Docker) |
|
||||
| **Auto-scroll** toggle | When enabled, the view scrolls to the bottom as new lines arrive |
|
||||
|
||||
## Capacity limits
|
||||
|
||||
To avoid browser memory issues, the log view keeps a maximum of **2,000 entries** in memory at a time. Older entries are dropped as new ones arrive. For deeper investigation, use the [per-container log viewer](/features/editor#log-viewer) in the Editor tab, or `docker compose logs` directly from the [Host Console](/features/host-console).
|
||||
|
||||
<Note>
|
||||
Log retention on the backend is controlled by **Settings → Developer → Log Retention Days** (default: 30 days). This affects historical logs stored in Sencho's database, not the live stream.
|
||||
</Note>
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: Host Console
|
||||
description: An interactive terminal on your host OS, directly in the browser — no SSH required.
|
||||
---
|
||||
|
||||
The **Console** tab opens a full interactive terminal session on the machine running Sencho. It behaves exactly like an SSH session, but without needing an SSH server, client, or key management.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/host-console/host-console-overview.png" alt="Host Console showing a PowerShell prompt inside the Sencho container working directory" />
|
||||
</Frame>
|
||||
|
||||
## What it is
|
||||
|
||||
The host console spawns a real PTY (pseudo-terminal) process on the Sencho host using `node-pty`. Your keystrokes are sent over a WebSocket and the terminal output is streamed back in real-time. The terminal emulator is [xterm.js](https://xtermjs.org/), the same engine used by VS Code's built-in terminal.
|
||||
|
||||
Features:
|
||||
- Full colour and cursor support
|
||||
- Tab completion (via the host shell)
|
||||
- Scrollback buffer (10,000 lines)
|
||||
- Automatic terminal resizing when you resize the browser window
|
||||
- Copy and paste
|
||||
|
||||
## Opening the console
|
||||
|
||||
Click **Console** in the top navigation bar. The session starts immediately in the stack's working directory if a stack is selected, otherwise in the `COMPOSE_DIR` root.
|
||||
|
||||
The header shows the connection status (**Connected** in green) and which node the console is attached to.
|
||||
|
||||
Click **Close Console** to end the session and terminate the shell process on the host.
|
||||
|
||||
## Shell type
|
||||
|
||||
The shell depends on the host OS:
|
||||
- **Linux/macOS hosts:** `bash` or `sh`
|
||||
- **Windows hosts (Docker Desktop):** PowerShell (as shown in the screenshot — the console opens inside the Sencho container's Windows environment)
|
||||
|
||||
## Security model
|
||||
|
||||
The host console has a stricter authentication requirement than other features:
|
||||
|
||||
- Requires a valid **browser session** (httpOnly cookie). Node-proxy tokens used for multi-node communication are explicitly blocked.
|
||||
- Each session is issued a short-lived **console token** (60-second TTL) before the WebSocket is established.
|
||||
- Because the console gives full shell access to the host, you should secure your Sencho instance with HTTPS and a strong password if it is exposed to a network.
|
||||
|
||||
<Warning>
|
||||
The host console provides unrestricted shell access to the machine running Sencho. Do not expose Sencho on a public network without HTTPS and strong authentication.
|
||||
</Warning>
|
||||
|
||||
## Common uses
|
||||
|
||||
- Inspecting files in your `COMPOSE_DIR` without leaving the browser
|
||||
- Running `docker compose logs --follow` or `docker ps` directly
|
||||
- Editing files with `nano` or `vim` for quick fixes
|
||||
- Running maintenance scripts or one-off commands on the host
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
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-overview.png" alt="Resources Hub showing disk footprint, quick clean panel, and images table" />
|
||||
</Frame>
|
||||
|
||||
## Docker disk footprint
|
||||
|
||||
The stacked bar at the top visualises how your Docker disk usage is distributed:
|
||||
|
||||
| Segment | Meaning |
|
||||
|---------|---------|
|
||||
| **Sencho Managed** (green) | Images used by stacks in your `COMPOSE_DIR` |
|
||||
| **External Projects** (orange) | Images used by Docker projects outside Sencho |
|
||||
| **Reclaimable** (gray) | Unused images and dangling layers safe to delete |
|
||||
|
||||
Click any segment to automatically 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** — 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 recognise (started outside it) |
|
||||
|
||||
Each button has a **⋮ More options** menu that lets you target **all Docker resources** instead of Sencho-only. Use this carefully — it can affect other Compose projects running on the same host.
|
||||
|
||||
A confirmation dialog appears before any destructive operation, showing a summary of what will be removed.
|
||||
|
||||
## 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
|
||||
- `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.
|
||||
|
||||
### Volumes
|
||||
|
||||
Lists all Docker volumes. Columns: name, driver, mount point, size, and managed status.
|
||||
|
||||
**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>
|
||||
|
||||
### Networks
|
||||
|
||||
Lists all Docker networks. Columns: name, driver, scope (`local`, `global`, `swarm`), and managed status.
|
||||
|
||||
**Filter buttons:** `All` · `Managed` · `External` · `System`
|
||||
|
||||
System networks (like `bridge`, `host`, `none`) are shown but cannot be deleted.
|
||||
|
||||
### 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`.
|
||||
@@ -24,8 +24,13 @@
|
||||
"group": "Features",
|
||||
"pages": [
|
||||
"features/overview",
|
||||
"features/dashboard",
|
||||
"features/stack-management",
|
||||
"features/editor",
|
||||
"features/resources",
|
||||
"features/app-store",
|
||||
"features/global-observability",
|
||||
"features/host-console",
|
||||
"features/multi-node",
|
||||
"features/alerts-notifications"
|
||||
]
|
||||
|
||||
Reference in New Issue
Block a user