Compose Panel docs

Roadmap

0.1 covers the V1 scope in product.md. The milestones P0–P6 that got there are recorded in CHANGELOG.md.

Nothing below is scheduled or promised. Each item changes a documented guarantee and needs its own ADR before any code.

After V1 the direction is to understand the host the stacks run on, not only the stacks themselves: observe resource use and service health, and carry out targeted server maintenance — without becoming a general-purpose Linux administration panel. Working tagline: Manage your stacks. Understand your server.

Access

  • Ubuntu host installation. Implemented (ADR 0031): interactive bootstrap for Ubuntu Server 24.04/26.04, official image, host Caddy/helper, private SSH by default and optional HTTPS with Basic Auth, plus read-only diagnostics (scripts/doctor.sh). Disposable VM validation remains required.
  • Use HTTPS and the SSH tunnel at the same time. Done in 0.2.0 (ADR 0012): COMPOSE_PANEL_PROXY_ORIGINS (a list) plus COMPOSE_PANEL_ALLOW_LOOPBACK. Host and Origin are validated per access point, and the cookie attribute is chosen per path.
  • Login CSRF across tabs and access modes. Make the token robust when several tabs are open or the access path changes.
  • Access diagnostics (0.2.0). A read-only /access page done in 0.2.0 (ADR 0013): it lists the configured paths with an honest status (verified by the panel / configured but unverifiable / verify externally) and never shows an access as secure from its configuration alone. No extra privileges.
  • Optional host diagnostics (later). Detect Caddy/Tailscale from a bounded, read-only JSON status file produced by an optional local collector with strictly limited permissions (systemctl is-active caddy, tailscale status|serve|funnel --json), disabled by default, served to the panel through a read-only mount — never a Tailscale or systemd socket, no keys or raw config. Own ADR first. Provider-agnostic: no Caddy/Tailscale detection hard-coded beyond the collected file.
  • Server health page (later). Fold the access diagnostics into a broader host view: external containers, systemd services and exposed ports, still read-only and without becoming a general Linux administration panel.

Usability

  • Controlled stack creation. Done (ADR 0024): name, raw Compose and optional .env, validated in the final directory and published without overwrite or deployment. No templates or catalogue.
  • Move between stacks without returning to the list. Done in 0.2.0 (ADR 0016): a persistent sidebar carries the section links, the stack list with the current stack highlighted, a local search filter, and a native mobile disclosure. Names only: no status, counter, badge or Docker call in the navigation.
  • Per-stack network options from a fixed allow-list, instead of editing raw YAML for common cases (see Dockge's edit screen).
  • Application actions. Done (ADR 0026): a stack points, through an x-compose-panel Compose extension, at the services whose Composer/npm/Bun scripts are exposed from each project's own manifest, and the panel runs them non-interactively through the existing operations machinery. No terminal, no free arguments, one running container per service.
  • External database explorer link. Done (ADR 0027): a stack declares a label and scalar query parameters in an x-compose-panel.database extension, and the panel shows a link to a separately deployed explorer (LibreDB Studio, Adminer…) behind a global base URL. Declarative only: the panel never contacts the explorer, holds no credential and opens no database. See the LibreDB deployment example.
  • Optional Caddy site management. Done (ADR 0030): the stack page previews the managed Caddy file for a domain → loopback upstream mapping, and — with the opt-in host helper behind a systemd socket — attaches and detaches it with validation, reload and honest rollback. One domain per file, only panel-owned files, externally deployed stacks read-only, no DNS/HTTPS checks.

Engine support

  • Podman. Add a Podman ComposeProvider behind the existing boundary (ADR 0005). Announce compatibility only after integration tests cover config, ps, pull, up, down, project names and file mounts.

Insights (read-only)

  • Deployment metadata. Done (ADR 0023): per-container OCI version, revision, source and local repository digests; separately declared stack.* labels for environment, branch, build and application links. No CI API or registry query. A declared stack.managed-by owner shows an informational badge and warning (ADR 0025).
  • Docker container inspection. Done (ADR 0014): a read-only view of the containers running on the host that are not part of a managed stack: status, image, published ports, restart policy, health, mounts (collapsed) and on-demand logs, via a dedicated ContainerInspector boundary. Categories (Managed, External Compose, Standalone) are derived from Compose labels, never from the name. Distinct from the host server-health page below.
  • Per-stack and per-container CPU/RAM, a top-consumers view and Docker disk usage (docker system df). Done (ADR 0015): the read-only /server page reads info/stats on load and system df on demand behind a short TTL cache, with no daemon, database or retained history. Remaining: validate Podman output parity like the other commands.
  • Simplified service health: unhealthy, restart loops, abnormal exits, surfaced with the stack they belong to. A current-state version (unhealthy/restarting, with non-zero exits listed apart) ships with /server (ADR 0015); restart-loop detection needs history and stays future.
  • Recreate pending. Done (ADR 0032): compare each container's com.docker.compose.config-hash label with compose config --hash, so a service still running a previous .env/Compose configuration shows that Up (not Restart) is needed. Read-only, hashes only, no new action; Compose 5.5.0+ only, and services sharing another container's namespaces or volumes are left unmarked.
  • Check a registry without pulling. Compare a tag's remote digest with the local one so "update available" shows before any download. Needs registry credentials in the container and honest handling of rate limits, private registries and local builds (ADR 0011 covers only images already pulled).

Host insights and maintenance

  • Read-only host status the container cannot see through namespaces: available packages and security updates, reboot required, filesystems, swap, zombie processes. Data comes from an optional, strictly allow-listed read-only host component — no arbitrary commands, no terminal, no free sudo.
  • Targeted maintenance using the distribution's own mechanism (for example unattended-upgrades): check, review and apply updates, then a controlled reboot with a separate confirmation. One package transaction at a time, audited, never a distribution upgrade. A single failing third-party repository should be identifiable and offered for temporary disable without blocking the rest.
  • Host toolbox (later, not accepted). A host-side runner, socket, sudoers entries or systemd units for administrator scripts stay out of scope; ADR 0026 covers only the application toolbox. A concrete need would need its own ADR.
  • Out of scope, even here: users, firewall, package repositories, arbitrary services and distribution upgrades. Compose Panel must not be marketed as a general server management panel.

Self-update

  • Update Compose Panel from the browser. Done in 0.3.0 (ADR 0018): About pulls the panel's own tag, then a one-shot updater container recreates only the panel service and waits for it to be healthy; the outcome is read back from Docker. Remaining: choosing a specific version (it would mean rewriting the image reference in the Compose file), and noticing a newer image without pulling it (see Check a registry without pulling above).

Compose

  • Compose override files. Stacks with compose.override.yaml, or several primary files, are refused today. Supporting them means editing and validating several files as one project (see ADR 0004).