patsissons/stacky repository overview

⁠stacky

A modern, compose-first Docker stack manager for your home lab: a better-looking, easier-to-use, more robust take on Dockge⁠.

• Compose files are the source of truth. Each stack is a plain directory (/opt/stacks/<name>/compose.yaml plus an optional .env). Stacky reads Dockge's layout as-is, so migrating means pointing it at the same directory.
• Modern UI. Covers stacks, a cross-stack containers table, logs, container shells and a real editor with schema completion and a diff and dry-run preview before every deploy. Click any container to inspect or edit just its service.
• Clear errors. Failed operations explain what went wrong and how to fix it.
• Image updates. Native registry digest and version-tag checks, with no extra containers to run. Checked on demand (per image, per stack, or everything), on a global schedule, or per container with a stacky.update.schedule label (nightly, weekly, 6h, cron…). Narrow which version tags count with stacky.tag.include / stacky.tag.exclude regex labels, and link each version, including the one deployed, to its release notes with stacky.link.template (the wud.* equivalents work too). Apply updates per service, per stack (including pinned versions), or all at once. Private registries work with a mounted docker config.json or STACKY_REGISTRY_* variables (WUD's WUD_REGISTRY_* ones too). What's Up Docker⁠ can optionally fill in images stacky can't check itself.
• Notifications. Pushover, ntfy, Gotify, Discord, Apprise or webhooks, for failed deploys, new image updates, unhealthy containers and self-updates. Each message names the host and stack it came from. Set a default for each event, then override it per stack or container with stacky.notify labels (e.g. stacky.notify.updates: true).
• File browser. A read-only view of the stacks directory and stacky's data directory, with a text viewer and an image viewer.
• App icons. Matched by image name from the selfh.st set, or picked with a stacky.display.icon label: any of What's Up Docker's icon sets, or an image URL.
• Self-update. Stacky can update its own stack from inside the UI, with automatic rollback.

Docs: https://stacky.lgtm.page⁠

⁠Install

curl -fsSL https://stacky.lgtm.page/install.sh | sh

Or do it by hand: create /opt/stacks/stacky/compose.yaml (see docker/compose.example.yaml⁠):

services:
  stacky:
    image: ghcr.io/patsissons/stacky:latest # or docker.io/patsissons/stacky
    restart: unless-stopped
    ports:
      - 5005:5005
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/app/data
      - /opt/stacks:/opt/stacks # host path MUST equal container path

cd /opt/stacks/stacky && docker compose up -d

Open http://<host>:5005 and create the admin account. From then on, stacky appears as a stack inside itself and can update itself.

⁠Configuration

Every variable is listed under Configuration⁠, and every compose label under Labels⁠. The in-app help (?) lists both too.

⁠Integrations

• REST API. Scripts and other apps can drive stacky with an API token (Settings → API tokens): curl -H "Authorization: Bearer stk_…" http://<host>:5005/api/stacks. Each instance serves an OpenAPI 3.1 document at /api/openapi.json. See the REST API reference⁠.
• AI agents (MCP). A built-in MCP⁠ server at /api/mcp lets Claude Code, Claude Desktop, Cursor and other agents inspect, edit, deploy and update stacks: claude mcp add --transport http stacky http://<host>:5005/api/mcp --header "Authorization: Bearer stk_…". See AI agents & MCP⁠.
• llms.txt. The docs are published for LLMs at stacky.lgtm.page/llms.txt⁠ (plus llms-full.txt and llms-small.txt), and this repository has its own llms.txt⁠.

⁠Development

Requirements: Node 24+, pnpm (version pinned in package.json), and Docker (OrbStack, Docker Desktop or a local engine).

pnpm install
pnpm dev        # server on :5005 (tsx watch) + web on :5173 (Vite, proxies /api and /ws)

In development the server uses STACKY_STACKS_DIR and STACKY_DATA_DIR from your environment. Point them at a scratch directory, e.g. STACKY_STACKS_DIR=$PWD/.dev/stacks STACKY_DATA_DIR=$PWD/.dev/data pnpm dev.

⁠Scripts

⁠Repository layout

apps/server     Hono API + WebSocket server
apps/web        React UI
apps/site       Docs site (Astro Starlight), deployed to stacky.lgtm.page
packages/shared Shared zod schemas and types
docker/         Dockerfile and example compose file

⁠Releases

Commits follow Conventional Commits⁠. Every push to main publishes ghcr.io/patsissons/stacky:edge (plus Docker Hub when credentials are configured), after running CI. CI is skipped when it would only repeat a result: a merge whose exact tree already passed PR CI (unless it changes the lockfile or main's CI caches have expired), or a release merge on top of a green run. release-please⁠ maintains a release PR; merging it tags a release and publishes X.Y.Z, X.Y, X (from 1.0 on) and latest for linux/amd64 and linux/arm64.

⁠License

MIT