mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-07-27 20:29:10 +00:00
Anso
b2f341b43d
* feat(convert): harden /api/convert endpoint with auth, validation, and tests Applies authMiddleware to the docker run to compose endpoint, validates that the payload is a non-empty string within an 8192 character budget, rejects inputs containing null bytes, and wraps composerize in a try/catch that surfaces a 422 with a clear message when the library cannot produce a services block. Adds a Vitest suite covering the auth gate, happy path, common flag coverage, boundary and null byte placement variants, and malformed command handling. * feat(editor): add From Docker Run tab to create stack dialog Introduces a third tab in the Create New Stack dialog that accepts a docker run command, calls the converter endpoint, and previews the returned compose YAML before writing it to a new stack directory. Uses the defensive toast pattern, clears the stale preview when the input changes, and rolls back the empty stack directory if saving the converted YAML fails so the user never ends up with an orphan stack. * docs(stack-management): document docker run to compose converter Adds a Convert from a docker run command section to the stack management page covering how to use the new tab, the list of supported flags, and troubleshooting for unparseable inputs. Screenshots show the empty tab, a successful conversion with the compose preview, the resulting stack in the editor, and the error toast surfaced when the input cannot be converted. Appends a matching entry to the troubleshooting page.
186 lines
8.7 KiB
Plaintext
186 lines
8.7 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.
|
|
|
|
## 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.
|
|
|
|
<Frame>
|
|
<img src="/images/editor/editor-overview.png" alt="Stack editor with control buttons" />
|
|
</Frame>
|
|
|
|
## Controlling a running stack
|
|
|
|
The stack header shows different actions depending on whether the stack is running or stopped.
|
|
|
|
**When running:**
|
|
|
|
| Button | Command | What it does |
|
|
|--------|---------|--------------|
|
|
| **Stop** | `docker compose stop` | Stops containers without removing them. State is preserved. |
|
|
| **Restart** | `docker compose restart` | Restarts all containers in the stack. |
|
|
| **Update** | `docker compose pull` + `up -d` | Pulls the latest image tags and recreates containers. |
|
|
| **Rollback** | Restores backup | Reverts compose and env files to the pre-deploy snapshot and redeploys. Only shown when a backup exists (Skipper+). |
|
|
| **Delete** | `down --volumes` + removes files | Stops and removes containers and volumes, then deletes the stack directory. |
|
|
|
|
**When stopped:**
|
|
|
|
| Button | Command | What it does |
|
|
|--------|---------|--------------|
|
|
| **Start** | `docker compose up -d` | Starts the stack. |
|
|
| **Update** | `docker compose pull` + `up -d` | Pulls the latest image tags and recreates containers. |
|
|
| **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>
|