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