102 lines
2.6 KiB
Markdown
102 lines
2.6 KiB
Markdown
# 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
|