# 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

```bash
# 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

# If deploy says caddy reload needs root:
sudo systemctl reload caddy
```

## 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](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