From 7c120c671c6bc8007d1e6f64b63940b6d7445b2f Mon Sep 17 00:00:00 2001 From: SaelixCode Date: Sun, 22 Mar 2026 22:43:53 -0400 Subject: [PATCH] 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 --- CHANGELOG.md | 1 + docs/features/app-store.mdx | 71 ++++++++++++++++++++++++ docs/features/dashboard.mdx | 60 +++++++++++++++++++++ docs/features/global-observability.mdx | 58 ++++++++++++++++++++ docs/features/host-console.mdx | 54 +++++++++++++++++++ docs/features/resources.mdx | 75 ++++++++++++++++++++++++++ docs/mint.json | 5 ++ 7 files changed, 324 insertions(+) create mode 100644 docs/features/app-store.mdx create mode 100644 docs/features/dashboard.mdx create mode 100644 docs/features/global-observability.mdx create mode 100644 docs/features/host-console.mdx create mode 100644 docs/features/resources.mdx diff --git a/CHANGELOG.md b/CHANGELOG.md index f1ca4c61..83a41406 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 `${{ }}` diff --git a/docs/features/app-store.mdx b/docs/features/app-store.mdx new file mode 100644 index 00000000..ebb90546 --- /dev/null +++ b/docs/features/app-store.mdx @@ -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. + + + App Store showing a grid of application templates with category filters + + +## 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. + + + Relative paths like `./config` are resolved relative to the stack directory inside your `COMPOSE_DIR`. Absolute paths map directly to the host filesystem. + + +### 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. diff --git a/docs/features/dashboard.mdx b/docs/features/dashboard.mdx new file mode 100644 index 00000000..2869e351 --- /dev/null +++ b/docs/features/dashboard.mdx @@ -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. + + + Sencho dashboard showing container stats, system stats, and historical charts + + +## 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. + + + Charts only show data from the moment Sencho started. If you just installed Sencho, they will be mostly empty until metrics accumulate. + + +## 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. diff --git a/docs/features/global-observability.mdx b/docs/features/global-observability.mdx new file mode 100644 index 00000000..4e396666 --- /dev/null +++ b/docs/features/global-observability.mdx @@ -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. + + + Global Observability view showing real-time log lines from multiple containers + + +## 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). + + + 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. + diff --git a/docs/features/host-console.mdx b/docs/features/host-console.mdx new file mode 100644 index 00000000..6108b2e3 --- /dev/null +++ b/docs/features/host-console.mdx @@ -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. + + + Host Console showing a PowerShell prompt inside the Sencho container working directory + + +## 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. + + + 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. + + +## 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 diff --git a/docs/features/resources.mdx b/docs/features/resources.mdx new file mode 100644 index 00000000..96c305c0 --- /dev/null +++ b/docs/features/resources.mdx @@ -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. + + + Resources Hub showing disk footprint, quick clean panel, and images table + + +## 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` + + + Deleting a volume is permanent. Any data stored in it will be lost. Always back up important volume data before pruning. + + +### 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`. diff --git a/docs/mint.json b/docs/mint.json index ed6d8365..e986e350 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -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" ]