---
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>
