Cockpit Docker/Podman Compose Plugin

Docker and Podman Compose management for Cockpit — start, stop, and monitor your stacks from a clean web UI.

• Dashboard listing all stacks with live status and container stats (auto-refreshing)
• Search and filter stacks by name and status
• Select multiple stacks and run Up, Restart, Pull, Down, or Kill on all of them at once
• Send long-running actions (Up, Pull) to the background and keep working, tracked in a floating panel
• Create new Compose Stacks or import existing ones directly from the WebUI
• Start, stop, restart, pause/unpause, pull, prune, scale, and kill stacks with one click
• Live log viewer per stack with per-service filtering and text search
• Interactive shell into any running service, with quote-aware command parsing and command history
• Run one-off commands with an option to override the image's entrypoint when needed
• YAML editor with syntax validation, diff view, auto-snapshot + .ENV editor
• Backup and restore stacks as .bak.tar.gz archives
• Docker and Podman support, including rootless and rootful setups, with a manual toggle when both are available

• Cockpit 300+
• Docker with the Compose plugin (docker compose v2+), or Podman with podman compose (Can run both at once, also supports rootless)

Cockpit comes pre-installed on Fedora and most RHEL-based systems. On other distros:

sudo systemctl enable --now cockpit.socket

Docker is not installed by default on most distros. Install it and add your user to the docker group:

sudo usermod -aG docker $USER

For rootless or rootful Docker/Podman, and the toggle to switch between them when both are detected, see Podman Compatibility in the wiki.

paru -S cockpit-compose

Every release publishes a -latest.rpm alias alongside the versioned one, so you can always grab the newest build without checking the Releases page for a version number:

curl -LO https://github.com/RXTX4816/cockpit-compose/releases/latest/download/cockpit-compose-latest.rpm
sudo rpm -i cockpit-compose-latest.rpm

curl -LO https://github.com/RXTX4816/cockpit-compose/releases/latest/download/cockpit-compose-latest.deb
sudo apt install ./cockpit-compose-latest.deb

curl -LO https://github.com/RXTX4816/cockpit-compose/releases/latest/download/cockpit-compose-latest.tar.gz
curl -LO https://github.com/RXTX4816/cockpit-compose/releases/latest/download/cockpit-compose-latest.tar.gz.sha256
sha256sum -c cockpit-compose-latest.tar.gz.sha256
tar -xzf cockpit-compose-latest.tar.gz
sudo mkdir -p /usr/share/cockpit/cockpit-compose
sudo cp -r cockpit-compose/* /usr/share/cockpit/cockpit-compose/

Then open Cockpit in your browser or hard-refresh the page — Docker Compose appears in the left navigation.

Requirements: Node.js 22+, npm

git clone https://github.com/RXTX4816/cockpit-compose.git
cd cockpit-compose
npm install
npm run build

To develop with live reload inside Cockpit, symlink the plugin:

mkdir -p ~/.local/share/cockpit
ln -s "$PWD/src" ~/.local/share/cockpit/cockpit-compose
npm run watch

Open http://localhost:9090 — Docker Compose appears in the sidebar automatically.

This plugin builds on @rxtx4816/cockpit-plugin-base-react — a shared foundation that provides bootstrapping, dark theme sync, i18n setup, reusable hooks and components, shared tooling config (TypeScript, ESLint, Vitest), and the QEMU VM test harness.

If you need to develop the base library and this plugin together locally, use yalc:

# In the cockpit-plugin-base-react repo
yalc publish            # or: yalc push (auto-pushes on change)

# In this repo
npm run base:add        # links the local yalc version
# ... make changes and test ...
npm run base:reset      # restores the npm registry version

QEMU VMs for testing across Arch, Debian, and Fedora with Docker, Podman, and both-runtime scenarios — plus two Fedora-only scenarios for rootless/rootful-specific bugs (podman-rootful: no rootless socket at all; full: Docker and Podman each running rootless and rootful simultaneously). Your src/ folder is mounted live so npm run watch changes appear in the browser without restarting anything. The VM harness is provided by the base library; plugin-specific config lives in scripts/test-vm.config.sh.

sudo pacman -S qemu-full cloud-image-utils wget   # one-time
npm run build
npm run vm download          # download base images (~500–700 MB each)
npm run vm start             # start every VM
# Open https://localhost:9090 — login: test / test

See docs/wiki/VM-Testing.md for the full list of VMs, ports, and scenario details.

Once a VM is running, Playwright drives Chromium against the live Cockpit UI. Each VM is a separate Playwright project — use --project to target one or more:

npm run vm start debian-podman && npm run vm wait debian-podman
npm run test:e2e -- --project=debian-podman   # single VM
npm run test:e2e                              # every VM (all must be running)
npm run test:e2e:ui                           # visual runner (great for debugging)

Specs needing real Cockpit Administrative access (e.g. rootful Podman with no rootless socket available) use loginWithAdminAccess from e2e/helpers/admin.ts instead of the default pluginPage fixture — see E2E Test Reference for why.

Tests live in e2e/ and cover login, stack list, YAML editor, and more. Check npm run vm status for running VMs and their ports.

See docs/wiki/VM-Testing.md for all VM ports, commands, and troubleshooting, and docs/wiki/E2E-Test-Reference.md for what every test actually covers.

The UI language follows Cockpit's language setting.

To add a new language, copy src/i18n/locales/en.json, translate the values, and register the file in src/i18n/index.ts.

Bug reports and feature requests: open an issue on GitHub.

Pull requests are welcome. Please make sure your changes pass CI (lint, typecheck, tests, and build) before submitting. See CONTRIBUTING.md for commit conventions and development setup. Open an issue first for significant feature additions.

Found a security vulnerability? Please report it privately — see SECURITY.md for the disclosure process. Do not open a public issue for security reports.

This repository has GitHub secret scanning and push protection enabled — do not commit secrets (API keys, tokens, passwords, .env files with real credentials, etc.). See SECURITY.md for the bypass process if a push is blocked by mistake.

AGPL-3.0-only © 2025–2026 RXTX4816.

Free and open-source software (copyleft). If you distribute a modified version — or run one as a service that users reach over a network — you must make your modified source available under the same license (AGPL §13). Earlier releases were under the MIT License; see LICENSE-HISTORY.md.

Bundled third-party components and their licenses are listed in THIRD-PARTY-NOTICES.txt, which is generated at build time and installed alongside the plugin.