panelctl quickstart

Minimal container management panel for rootless Podman + Caddy.

Base directory

/var/lib/containers

Generated structure

/var/lib/containers/
├── stacks/<app>/compose.yaml    # Compose file per app
├── volumes/<app>/data           # Persistent volumes
├── routes/routes.caddy          # Single aggregate Caddy routes file
├── backups/<app>-<timestamp>.zip # Volume backups
└── state/apps/<app>.env         # App manifest

All app routes are written to a single routes/routes.caddy file that Caddy imports.

Quick workflow

# Create a new app (single domain)
panelctl init whoami whoami.srazka.com 18080 true

# Create with multiple domains
panelctl init myapp "app.srazka.com,www.srazka.com" 18081 true

# Create with wildcard domain (requires DNS challenge in Caddy)
panelctl init wild "*.srazka.com" 18082 false

# Deploy (compose up + caddy reload)
panelctl deploy whoami

# Check container status
panelctl status whoami

# View logs
panelctl logs whoami --tail 50

# Restart containers
panelctl restart whoami

# Stop containers
panelctl stop whoami

# Validate compose file
panelctl validate-compose whoami

# Backup volumes to zip
panelctl backup whoami

# List backups
panelctl list-backups whoami

# Restore from backup
panelctl restore whoami whoami-20260101-120000.zip

# List all apps
panelctl list

# Show app manifest
panelctl show whoami

# Remove app (keeps volumes)
panelctl remove whoami --keep-volumes

# Remove app and all data
panelctl remove whoami

Notes

• The default compose file uses traefik/whoami for smoke testing — edit before production use.
• App names must be lowercase slugs ([a-z0-9-]).
• Wildcard domains (*.example.com) require DNS challenge in Caddy (provider-specific).
• Backups stop containers for consistency, then restart if they were running.
• If deploy reports XDG_RUNTIME_DIR missing, enable lingering:

  sudo loginctl enable-linger reudy
  

Web UI & API

• Nix runs panel-api as a systemd service on 127.0.0.1:9911.
• Caddy proxies https://panel.srazka.com → panel-api with Authelia forward_auth.
• Open https://panel.srazka.com for the web UI.
• API docs: API.md

Web UI features

• Create apps with multiple domains and wildcard support
• Live container status indicators (auto-refreshes)
• Deploy, restart, stop, remove from the UI
• Inline compose editor with save, validate, and save+deploy
• Log viewer with configurable tail length
• Volume backup management: create, list, download, restore