Docker apps & stacks

MZPanel runs containerized workloads on your servers two ways: single apps (one image) and stacks (a full docker compose file). You manage both from a server’s Apps section (/servers/:id/apps) — a Stacks, Containers and Resources view with one shared Deploy drawer — and deploy catalog apps from the account-level Marketplace. These features are gated to Pro and up.

Marketplace 1-click apps

The Marketplace is one catalog of apps and extensions. Pick an app — n8n, Ghost, an AI UI, and more — choose a target server, give it a domain, and deploy. The Marketplace is state-aware: it shows what’s already installed on each server (an “Installed N/M” badge) and lets you update or remove in place, so the full lifecycle lives in one screen.

Deploying an app from the catalog provisions the container, wires up the nginx vhost, and issues SSL — the same flow you’d get configuring it by hand, without the steps.

Compose stacks

A stack is a docker compose file you deploy as a unit from the Deploy stack action on the Stacks tab. MZPanel validates the compose (docker compose config) before bringing it up, so YAML and missing-variable errors surface inline instead of failing halfway. Day-2 actions include Update images (pull + recreate), health-depth (it reads the real failing healthcheck reason and restart count, not a guess), and per-service inspection — click a service to open its container drawer.

Stacks back up as a unit too — a DB-consistent backup captures the compose file, logical database dumps, and non-database volumes for a full restore.

Build from git — Dockerfile or Nixpacks

In the Deploy drawer, pick From Git to point an app or stack at a repository. MZPanel clones and builds it on the box, then runs it. The Builder choice controls how:

• Auto (default) — uses your repo’s Dockerfile if one is present; otherwise it auto-detects the stack with Nixpacks (Node, Python, Go, Ruby, and more) and installs Nixpacks on demand, so you don’t need a Dockerfile at all.
• Dockerfile — force building your Dockerfile (set a custom path if it isn’t Dockerfile at the repo root).
• Nixpacks — force Nixpacks even if a Dockerfile exists.

Pushing a new commit can trigger an automatic rebuild via a connected repo webhook. Builds run a RAM/disk preflight first so a low-memory VPS isn’t pushed over the edge (override with force only when you know it fits). Connect repos once under Git connections to build private repositories without pasting a token.

Source code stays on the box

Builds run on your VPS through the agent, not on MZPanel infrastructure — your source code never leaves your server. The trade-off is a short spike of CPU/RAM during the build; the preflight guard keeps it in check.

Env store

Set environment variables per app or stack from the Env tab — no SSH editing of .env files. Values are encrypted at rest on the box (sealed with the agent’s own key; only the key name stays readable for the list) and unsealed only into a transient in-memory --env-file when the container runs, so a stray disk snapshot or backup never leaks them. In the list, values are masked with a reveal action, survive rebuilds, and stay out of build logs.

Releases & rollback

Each successful build is kept as a release. If a deploy goes bad, roll back to a previous release instantly from the Releases view — it reuses the already-built image, so there’s no rebuild.

PR preview environments

Apps and stacks built from git can get a throwaway preview environment per pull request, torn down when the PR closes. This mirrors the site preview flow — see Staging & deploys for how previews are triggered and the fork-PR safety rule.

App proxy — reaching apps privately

Admin UIs like phpMyAdmin, pgAdmin, and webmail open as real pages on a MZPanel domain — not an iframe — through a reverse proxy that tunnels HTTP over the agent’s existing WebSocket to the app listening on localhost on your box.

Because the app only listens on 127.0.0.1 and your box opens no public port for it, the box hostname and IP stay fully hidden — there’s nothing to scan or attack. A proxy session is owner-scoped and time-limited; large data transfers (such as database export/import) go through native tools, not the proxy.

How it works

Actions dispatch app.* and stack.* jobs to the server’s agent, which runs them natively (never calling mz):

Action	Job	Agent runs
Deploy catalog / image app	app.create	app create <name> --domain … --image …
Build app from git	app.build	preflight → git clone --depth 1 → Dockerfile or nixpacks build → run
Rebuild / rollback	app.rebuild / app.rollback	rebuild from saved repo, or re-point at a kept release
Env store	app.env-set / -list	seals values at rest; unseals to a tmpfs env-file at run
Deploy stack	stack.deploy	validates docker compose config, then brings it up
Update stack images	stack.pull	pull + recreate
Stack build from git	stack.build	clones + builds Compose services from source

The container, image, release history and sealed env live on the box; MZPanel’s control plane records only the connected repo/branch and proxy session wiring.

CLI & automation

Each action maps to an mz app / mz stack command on the box — the same engine the dashboard drives. SSH in and run them, or let an on-box AI (ClaudeCode) run them:

mz app build web --git https://github.com/you/app --branch main --builder auto --json
mz app releases web --json
mz app rollback web --to <seq>
mz app env set web KEY=value --json          # sealed at rest
mz stack list --json
mz stack rebuild db --json

Pass a sub-action and --json for machine output. See The mz CLI and the command catalog.

Gotchas & troubleshooting

• Auto builder needs neither a Dockerfile nor Nixpacks pre-installed. With no Dockerfile, MZPanel installs Nixpacks on the box on first use and auto-detects your stack; force Dockerfile or Nixpacks in the Deploy drawer to override.
• Build preflight can refuse on a small VPS. A low-RAM/disk box is guarded so a build doesn’t OOM it — free space or use the force override only if the build fits.
• Rollback reuses the built image. It’s instant and skips the rebuild, but it won’t undo external changes (databases, volumes) made since that release.
• The app proxy is not for bulk data. It’s for admin UIs; database export/import and large transfers use native tools, not the tunnel.
• Needs the agent online. Deploy, build, env changes and the proxy all run through the agent; when the server is offline these actions are unavailable.

Related

• Marketplace — the account-level catalog of 1-click apps.
• Server apps — the per-server Containers / Stacks / Resources view.
• Staging & deploys — atomic release deploys and PR previews for non-container sites.
• Manage databases — the DB admin UIs the proxy serves.
• Tiers & quotas — what each plan includes.