mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-07-26 11:49:16 +00:00
Anso
a65a1c0e86
* feat(stack-view): per-container health strip and structured logs viewer Replaces the flat container list with a per-container health strip showing healthcheck state, uptime, port mapping with an open-app link, and live cpu/memory/network sparklines fed by a 60-sample ring buffer on the stats WebSocket. Adds a structured logs viewer that parses docker timestamps (emitted by the -t flag on the logs stream) and classifies each line by level. Rows render as a DOM grid with filter pills (all / info / warn / err with count), following indicator, and plain-text download. A segmented toggle switches between the structured viewer and the original xterm view; the choice is persisted in localStorage. * fix(stack-view): disable no-control-regex for ANSI escape pattern ANSI escape sequences start with ESC (0x1B), which is a control character. The regex is intentional and cannot be rewritten without it.
239 lines
12 KiB
Plaintext
239 lines
12 KiB
Plaintext
---
|
||
title: Stack Management
|
||
description: Create, deploy, control, and remove Docker Compose stacks.
|
||
---
|
||
|
||
A **stack** in Sencho is a Docker Compose project: a directory inside your `COMPOSE_DIR` that contains at least a `compose.yaml` (or `docker-compose.yml`) file. Sencho automatically discovers every subdirectory as a stack.
|
||
|
||
<Frame>
|
||
<img src="/images/stack-management/create-stack-dialog.png" alt="Create New Stack dialog" />
|
||
</Frame>
|
||
|
||
## Creating a stack
|
||
|
||
Click **Create Stack** in the left sidebar. Enter a name and click **Create**.
|
||
|
||
**Naming rules:**
|
||
- Lowercase letters, numbers, and hyphens only (e.g. `my-app`, `nextcloud`)
|
||
- No spaces or special characters
|
||
- Must be unique; duplicates are rejected
|
||
|
||
Sencho creates a new directory inside `COMPOSE_DIR` with a blank `compose.yaml` file. You'll land in the editor automatically.
|
||
|
||
## Convert from a docker run command
|
||
|
||
If you have a `docker run` command handy (from a README, a forum post, or your shell history), Sencho can turn it into a ready-to-deploy `compose.yaml` without hand translation.
|
||
|
||
Open the **Create New Stack** dialog and switch to the **From Docker Run** tab.
|
||
|
||
<Frame>
|
||
<img src="/images/stack-management/convert-tab-empty.png" alt="Create stack dialog on the From Docker Run tab" />
|
||
</Frame>
|
||
|
||
### How to use it
|
||
|
||
1. Enter a **Stack Name**. Same rules as the Empty tab (lowercase, hyphens, unique).
|
||
2. Paste your full command into **Paste your docker run command**. The whole command should be on one logical line; line continuations with `\` are fine.
|
||
3. Click **Convert**. Sencho parses the command and shows the resulting compose YAML in a read-only preview below.
|
||
4. Review the YAML. If it looks right, click **Create Stack**. Sencho creates the stack directory and writes the converted YAML into `compose.yaml`.
|
||
5. The editor opens on the new stack. Click **Start** to deploy it.
|
||
|
||
<Frame>
|
||
<img src="/images/stack-management/convert-tab-result.png" alt="Converted compose YAML preview before creating the stack" />
|
||
</Frame>
|
||
|
||
<Frame>
|
||
<img src="/images/stack-management/convert-stack-created.png" alt="Newly created stack loaded in the editor after conversion" />
|
||
</Frame>
|
||
|
||
### Supported flags
|
||
|
||
The converter handles the flags you reach for most often:
|
||
|
||
| Flag | Purpose |
|
||
|------|---------|
|
||
| `-d` / `--detach` | Detached mode (implied by compose) |
|
||
| `--name` | Container name |
|
||
| `-p` / `--publish` | Port mappings (`host:container`) |
|
||
| `-v` / `--volume` | Volumes and bind mounts |
|
||
| `-e` / `--env` | Environment variables |
|
||
| `--env-file` | Env file reference |
|
||
| `--restart` | Restart policy (`no`, `always`, `unless-stopped`, `on-failure`) |
|
||
| `--network` | Attach to a named network |
|
||
| `--label` | Container labels |
|
||
| `--user` | Run as a specific user |
|
||
| `--workdir` | Set the working directory |
|
||
| `--entrypoint` | Override the entrypoint |
|
||
| `--cap-add` / `--cap-drop` | Linux capabilities |
|
||
| `--privileged` | Privileged mode |
|
||
| `--read-only` | Read-only root filesystem |
|
||
| `--tmpfs` | Temporary filesystem mount |
|
||
|
||
The image tag is taken from the final positional argument (for example `nginx:alpine`). Any trailing command arguments are preserved as the service `command`.
|
||
|
||
### Troubleshooting
|
||
|
||
<Frame>
|
||
<img src="/images/stack-management/convert-tab-error.png" alt="Error toast shown when the converter cannot parse the input" />
|
||
</Frame>
|
||
|
||
If the converter cannot produce a usable compose file, the request fails with a clear error toast. Common causes:
|
||
|
||
- **Not a docker run command.** The input must begin with `docker run` and include an image reference. Free-form text, `docker compose` commands, and shell pipelines are rejected.
|
||
- **Unrecognized flag.** The parser supports the flags listed above. Rare flags (such as `--userns`, `--ipc`, custom runtime options) may not be recognized. Remove the flag, convert the rest, and add it back by hand in the editor.
|
||
- **Quoting issues.** Multi-line commands with embedded quotes sometimes confuse the parser. Paste the command as a single line with escaped quotes, or simplify the command first.
|
||
- **Command is too long.** The endpoint accepts commands up to 8192 characters. Longer inputs are rejected; trim anything you do not need and convert in pieces.
|
||
|
||
When a flag is not supported, paste the output you do get into the **Empty** tab as a starting point and fill in the rest by editing `compose.yaml` directly.
|
||
|
||
## The stack list
|
||
|
||
All discovered stacks appear in the left sidebar. Each shows a color-coded status indicator:
|
||
|
||
| Indicator | Meaning |
|
||
|-----------|---------|
|
||
| `UP` (green) | All containers running |
|
||
| `DN` (red) | One or more containers exited |
|
||
| No indicator | No containers / status unknown |
|
||
|
||
Use the **search box** above the list to filter stacks by name.
|
||
|
||
## Stack header
|
||
|
||
Opening a stack puts identity and state front and center.
|
||
|
||
<Frame>
|
||
<img src="/images/stack-view/identity-header.png" alt="Stack identity header with breadcrumb, title, state pill, image digest, and action row" />
|
||
</Frame>
|
||
|
||
The header answers three questions at a glance:
|
||
|
||
- **What is this?** A breadcrumb (`node › stacks › name`) and the stack name as the title.
|
||
- **Is it healthy?** A pulsing pill to the right of the title reports the live state:
|
||
- `running · healthy` (green) when at least one container reports a passing healthcheck.
|
||
- `running · unhealthy` (red) when any container reports a failing healthcheck.
|
||
- `running · starting` (amber) during the Docker healthcheck start period.
|
||
- `running` (green) when no healthcheck is defined.
|
||
- `exited` (red) when no containers are up.
|
||
- **What does it ship?** A mono line under the title shows the primary image tag and the short image digest, with a copy button to grab the full digest.
|
||
|
||
## Container health strip
|
||
|
||
Below the header, each container in the stack gets a single row that answers "is this piece working, and how do I reach it?" without expanding anything.
|
||
|
||
<Frame>
|
||
<img src="/images/stack-view/health-strip-logs.png" alt="Stack view showing the per-container health strip above the structured logs viewer" />
|
||
</Frame>
|
||
|
||
Each row includes:
|
||
|
||
- **Health badge.** A colored glyph reports the Docker healthcheck state: `✓` green for passing, `✗` red for failing, `…` amber while the healthcheck start period is still in flight. Containers without a `healthcheck:` block show a neutral `✓`.
|
||
- **Container name** in mono.
|
||
- **Meta line.** Uptime (`up 20 hours`), healthcheck state when one is defined, and the primary port mapping (`6875 → 80/tcp`).
|
||
- **Open link.** When the container publishes a port, an `open ↗` link launches the app in a new tab using the active node's hostname.
|
||
- **Live stat tiles.** Three tiles show CPU, memory, and network I/O with a rolling 60-sample sparkline. The sparkline uses the cyan data color and refreshes roughly every 1.5 seconds.
|
||
- **Action icons.** Shortcuts to open this container's logs or a bash shell.
|
||
|
||
## Logs viewer
|
||
|
||
The logs area at the bottom of the stack view has two modes. Toggle between them with the segmented control in the top-right of the panel; your choice is remembered for next time.
|
||
|
||
**Structured** (default) parses every line into a DOM row with three columns: local time, level badge, and message. Level detection is automatic:
|
||
|
||
- `err` rows get a red left rail and a subtle rose tint.
|
||
- `warn` rows get a warm tint.
|
||
- `info` rows render plainly.
|
||
|
||
The toolbar includes:
|
||
|
||
- **Following indicator.** A pulsing green dot reads `following` while auto-scroll is engaged. Scrolling up stops follow; a `resume follow` link re-engages it and jumps to the bottom.
|
||
- **Level filter.** `all · info · warn · err` pills. The `err` pill shows the running error count as a badge.
|
||
- **Download.** Exports the current buffer as a plain text file.
|
||
|
||
The structured viewer holds up to 10,000 lines; older entries are dropped from the top as new ones arrive.
|
||
|
||
**Raw terminal** keeps the original xterm-based viewer for cases where ANSI art, control sequences, or interactive TTY output matter. Lines include the raw ISO timestamp.
|
||
|
||
## Deploying a stack
|
||
|
||
Select a stack and click **Start** (or **Deploy** from the context menu) in the stack header. This runs `docker compose up -d`, pulling images if needed and creating or recreating containers.
|
||
|
||
## Controlling a running stack
|
||
|
||
The stack header groups actions by frequency of use. The most common action is the filled cyan button on the left, everyday secondaries sit next to it, and destructive or occasional actions are tucked behind the `⋯` overflow.
|
||
|
||
**When running:**
|
||
|
||
| Placement | Button | Command | What it does |
|
||
|-----------|--------|---------|--------------|
|
||
| Primary | **Restart** | `docker compose restart` | Restarts all containers in the stack. |
|
||
| Secondary | **Stop** | `docker compose stop` | Stops containers without removing them. State is preserved. |
|
||
| Secondary | **Update** | `docker compose pull` + `up -d` | Pulls the latest image tags and recreates containers. |
|
||
| Overflow `⋯` | **Rollback** | Restores backup | Reverts compose and env files to the pre-deploy snapshot and redeploys. Only shown when a backup exists (Skipper+). |
|
||
| Overflow `⋯` | **Scan config** | Trivy config scan | Scans the compose file for misconfigurations (Skipper+, admin). |
|
||
| Overflow `⋯` | **Delete** | `down --volumes` + removes files | Stops and removes containers and volumes, then deletes the stack directory. |
|
||
|
||
**When stopped:**
|
||
|
||
| Placement | Button | Command | What it does |
|
||
|-----------|--------|---------|--------------|
|
||
| Primary | **Start** | `docker compose up -d` | Starts the stack. |
|
||
| Secondary | **Update** | `docker compose pull` + `up -d` | Pulls the latest image tags and recreates containers. |
|
||
| Overflow `⋯` | **Delete** | Removes files | Deletes the stack directory. |
|
||
|
||
<Warning>
|
||
**Delete** is irreversible. It removes the stack directory, including `compose.yaml`, `.env`, and any bind-mounted files stored there. Back up important files before deleting.
|
||
</Warning>
|
||
|
||
<Note>
|
||
Stack directories often contain root-owned files, either because Docker Compose creates them, or because the stacks were originally set up outside of Sencho with `sudo`. Sencho handles this automatically: if a normal deletion fails due to permissions, it uses Docker to clean up root-owned files. No manual intervention is needed in the standard setup.
|
||
</Note>
|
||
|
||
## Stack context menu
|
||
|
||
Right-click any stack in the sidebar to open the context menu. The menu adapts to the stack's current state; only relevant actions are shown.
|
||
|
||
**Running stack:**
|
||
|
||
<Frame>
|
||
<img src="/images/stack-management/context-menu-running.png" alt="Context menu for a running stack" />
|
||
</Frame>
|
||
|
||
**Stopped stack:**
|
||
|
||
<Frame>
|
||
<img src="/images/stack-management/context-menu-stopped.png" alt="Context menu for a stopped stack" />
|
||
</Frame>
|
||
|
||
### Available actions
|
||
|
||
- **Alerts** - configure metric-based alerting rules for this stack
|
||
- **Labels** - assign organizational labels (Skipper+)
|
||
- **Check for updates** - manually trigger an image update check
|
||
- **Open App** - open the stack's web interface in a new tab (only shown when the stack is running and exposes a web port)
|
||
- **Deploy** - start the stack (shown when stopped)
|
||
- **Stop** - stop all containers (shown when running)
|
||
- **Restart** - restart all containers (shown when running)
|
||
- **Update** - pull latest images and recreate containers (shown when running)
|
||
- **Delete** - stop and remove the stack (admin only)
|
||
|
||
All actions are disabled while another operation is in progress on that stack.
|
||
|
||
## Scanning for stacks
|
||
|
||
If you place Docker Compose files directly into the stacks directory (for example, via `scp`, a file manager, or the command line), you can import them without going through the full "Create Stack" flow.
|
||
|
||
Click the **folder-search icon** next to the "Create Stack" button in the sidebar. Sencho scans the configured stacks directory and reports what it finds:
|
||
|
||
<Frame>
|
||
<img src="/images/stack-scanning/scan-button-sidebar.png" alt="Scan stacks folder button in the sidebar" />
|
||
</Frame>
|
||
|
||
- **New stacks detected** - a success notification lists the newly discovered stack names, and they appear immediately in the sidebar
|
||
- **Stacks removed from disk** - an informational notification lists stacks that are no longer present in the directory
|
||
- **No changes** - a notification confirms no new stacks were found
|
||
|
||
<Tip>
|
||
Any subdirectory inside your `COMPOSE_DIR` that contains a `compose.yaml`, `compose.yml`, `docker-compose.yaml`, or `docker-compose.yml` file is recognized as a valid stack.
|
||
</Tip>
|