gsadmin/sencho
1
0
Fork 0
mirror of https://github.com/Studio-Saelix/sencho.git synced 2026-07-26 11:49:16 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
82aabfe64caa43548757f0f13fcaadde1b5a0518
sencho/docs/features/stack-management.mdx
T
Anso 82aabfe64c feat(stack-view): identity header with health state and action hierarchy (#688) 
* feat(stack-view): identity header with health state and action hierarchy

Redesign the stack view header around three questions: what is this, is it
healthy, what does it do. Surface Docker healthcheck state, primary image
tag, and image digest; group actions by frequency.

- Backend: extend /api/stacks/:name/containers with healthStatus (healthy /
  unhealthy / starting / none), Image, and ImageID by inspecting each
  container in parallel.
- Frontend: replace flat CardHeader with breadcrumb, italic serif title,
  colored state pill with pulse, and a mono image/digest line with a
  one-click copy button for the full digest.
- Frontend: action hierarchy - primary cyan Restart/Start, outline Stop and
  Update, and an overflow menu for Rollback, Scan config, and Delete.
- Docs: new Stack header section and updated controlling-a-running-stack
  tables showing primary/secondary/overflow grouping.

* test(e2e): open overflow menu to reach stack Delete action

Destructive actions now live under the stack toolbar overflow menu rather
than as a flat top-level button, so the delete flow must click More actions
before selecting the Delete menu item.
2026-04-18 23:38:56 -04:00

202 lines
10 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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.
## 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>
Reference in New Issue View Git Blame Copy Permalink