reudy-net/panel
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Deployments, auto deploy, service routes, live logs, metrics and a terminal

Browse source 
Deployments: deploy, restart and git sync now run in the background, one at
a time per app (a newer request replaces a queued one). Each run is recorded
in SQLite with its log, streamed to the UI while it runs, and can be
cancelled. Any earlier deployment can be deployed again, which rolls back to
its commit, or to its saved compose file for compose apps.

Auto deploy: POST /hooks/<app>, verified with the app's secret (Forgejo,
Gitea and GitHub HMAC signatures, or the secret as a token for CI). With a
Forgejo token stored, the panel adds the webhook to the repository itself.
The NixOS module routes /hooks/* past Authelia. Caddy matches the cleaned
path but forwards the original, so the panel refuses dot segments and only
accepts webhook deliveries from that route (tagged with X-Panel-Hook).

Domains: a route can point at a compose service's container port
("web:8080"). The panel picks a free 127.0.0.1 port and panelctl publishes
it through a generated .panel-ports.yaml override, so compose files need no
ports: section. Existing host:port upstreams keep working.

Logs stream live over server-sent events, with service and text filters.
A sampler keeps an hour of CPU and memory per container for the new
Monitoring tab. The Terminal tab opens `podman exec` in a container over a
WebSocket, using xterm.js bundled by the Nix package.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UbWSNkXxZhYf7eqHTyx3Bf
This commit is contained in:
agent 2026-09-27 19:05:19 +00:00
parent e11fc00840
commit 71fed39f17
8 changed files with 2997 additions and 313 deletions
Download patch file Download diff file Expand all files Collapse all files

107
API.md
View file

@ -44,9 +44,9 @@ Default bind: `127.0.0.1:9911`
| Method | Path | Description |
|--------|------|-------------|
| POST | `/apps/init` | Create a new app |
| POST | `/apps/<name>/routes` | Update routes (hot — Caddy reloads automatically) |
| POST | `/apps/<name>/deploy` | Deploy (compose up + caddy reload) |
| POST | `/apps/<name>/restart` | Restart (compose down + up) |
| POST | `/apps/<name>/routes` | Update routes (hot — Caddy reloads automatically); answers `needs_deploy` when a newly published port needs a deploy |
| POST | `/apps/<name>/deploy` | Queue a deployment (compose up + caddy reload) — see *Deployments* |
| POST | `/apps/<name>/restart` | Queue a restart (compose down + up) |
| POST | `/apps/<name>/stop` | Stop (compose down) |
| POST | `/apps/<name>/render-route` | Re-render Caddy route |
| POST | `/apps/<name>/compose` | Save compose.yaml content |
@ -54,20 +54,90 @@ Default bind: `127.0.0.1:9911`
| POST | `/apps/<name>/backup` | Create volume backup (zip) |
| POST | `/apps/<name>/restore` | Restore from backup |
| POST | `/apps/<name>/remove` | Remove app |
| POST | `/apps/<name>/repo-pull` | Git apps: fetch branch, hard-reset checkout to it, redeploy |
| POST | `/apps/<name>/env` | Replace environment variables: `{"vars": [...], "inject": true, "deploy": false}` |
| POST | `/apps/<name>/repo-pull` | Git apps: queue a sync (fetch branch, hard-reset checkout to it, deploy) |
| POST | `/apps/<name>/env` | Replace environment variables: `{"vars": [...], "inject": true, "deploy": false}` (`deploy` queues a deployment) |
| POST | `/apps/<name>/volume-clear` | Stop the app and empty its default data folder |
| POST | `/apps/<name>/autodeploy` | Auto deploy on push: `{"enabled": true, "register": true, "regenerate": false}` |
| POST | `/compose/inspect` | `{"content": "..."}` → services of a compose file and the container ports they mention |
Write operations are serialised per app. While one runs, another write to the
same app returns `409` with `{"ok": false, "error": "...", "busy": "deploy"}`.
`deploy` returns the compose output in `stdout` (or `stderr` on failure).
Deploys, restarts and syncs are the exception: they are queued (see below).
### Deployments
`deploy`, `restart` and `repo-pull` run in the background, one at a time per
app, and answer `202` at once with the queued deployment:
```json
{"ok": true, "deployment": {"id": 12, "app": "blog", "kind": "sync", "trigger": "manual", "title": "Sync from git", "status": "queued", ...}}
```
A newer request replaces one that is still queued (that one ends as
`cancelled`, "superseded by #13"). Send `{"wait": true}` to block until it
ends; the answer then has `ok`, the `deployment` and its log in `stdout` /
`stderr`, like the old synchronous API.
| Method | Path | Description |
|--------|------|-------------|
| GET | `/apps/<name>/deployments?limit=N` | History, newest first (the last 50 are kept, with logs) |
| GET | `/deployments/<id>` | One deployment |
| GET | `/deployments/<id>/log` | Its full log |
| GET | `/deployments/<id>/stream?offset=N` | Server-sent events: `status`, `log` (`{text, offset}`) while it runs, then `done` |
| POST | `/deployments/<id>/cancel` | Cancel a queued or running deployment |
| POST | `/deployments/<id>/redeploy` | Deploy that deployment again: its commit for git apps, its saved compose file otherwise (a rollback) |
A deployment has `status` (`queued`, `running`, `success`, `failed`,
`cancelled`), `kind` (`deploy`, `sync`, `restart`), `trigger` (`manual`,
`webhook`, `rollback`), `commit_sha` / `commit_subject` / `commit_author`
for git apps, `error`, and `created` / `started` / `finished` / `duration`.
### Webhooks (auto deploy)
`POST /hooks/<name>` deploys an app whose auto deploy is switched on. It is
routed past Authelia by the NixOS module and authenticated with the app's
secret instead: an `X-Forgejo-Signature` / `X-Gitea-Signature` /
`X-Hub-Signature-256` HMAC of the body, or the secret itself as
`X-Gitlab-Token`, `X-Panel-Token` or `?token=`. For git apps a push to another
branch is ignored; everything else queues a sync.
`GET /apps/<name>/autodeploy` returns `enabled`, the webhook `url` and
`secret`, the `branch`, whether the panel registered the webhook on Forgejo
(`forgejo.hook_id`) and the `last` delivery. Enabling it with a Forgejo token
stored adds the webhook to the repository (the token needs write access to it).
### Logs, metrics and terminal
| Method | Path | Description |
|--------|------|-------------|
| GET | `/apps/<name>/logs/stream?tail=N&service=S` | Server-sent events: `lines` (`{lines: [...]}`) as the containers write them, `end` when they stop |
| GET | `/apps/<name>/stats` | Per container: current CPU / memory / network / block IO and an hour of `[time, cpu %, memory bytes]` history |
| GET | `/apps/<name>/services` | Compose services with the container ports they mention |
| GET (WebSocket) | `/apps/<name>/terminal?container=C` | Shell in a container (`podman exec`). Send `{"type": "input", "data": "..."}` and `{"type": "resize", "cols", "rows"}`; output arrives as binary frames |
### Route targets
A route points at the container port it serves instead of an upstream:
```json
{"domain": "blog.reudy.net", "target": "web:2368"}
```
`target` is a port (`2368`, for a compose file with one service),
`service:port`, or `host:port` for something outside the app
(`127.0.0.1:8081`, same as the older `upstream` field). For service targets
the panel picks a free port in 18000–19999 and `panelctl` publishes the
container port on `127.0.0.1:<port>` through a generated
`.panel-ports.yaml` compose override, so compose files need no `ports:`.
Routes keep their port when they are saved again. In `/status` such routes
have `service` and `port` next to the `upstream` Caddy uses.
### Create app (git repository, with environment variables)
```json
{
"name": "blog",
"routes": [{"domain": "blog.reudy.net", "upstream": "127.0.0.1:18090"}],
"routes": [{"domain": "blog.reudy.net", "target": "web:2368"}],
"auth": true,
"source_type": "git",
"repo_url": "https://git.reudy.net/reudy-net/blog.git",
@ -87,18 +157,6 @@ same app returns `409` with `{"ok": false, "error": "...", "busy": "deploy"}`.
- The older `source_type: "github"` with `github_url` / `github_branch` /
`github_pat` is still accepted.
### Sync response (`repo-pull`)
```json
{
"ok": true,
"stdout": "HEAD is now at d7df557 Bump image tag\n...compose output...",
"before": {"sha": "4fb7976...", "short": "4fb7976", "subject": "Initial compose", "author": "reudy", "time": 1790460618},
"after": {"sha": "d7df557...", "short": "d7df557", "subject": "Bump image tag", "author": "reudy", "time": 1790460643},
"changed": true
}
```
### Status response (`/status`)
```json
@ -113,7 +171,10 @@ same app returns `409` with `{"ok": false, "error": "...", "busy": "deploy"}`.
"compose_file": "/var/lib/containers/stacks/whoami/compose.yaml",
"repo_url": "",
"repo_branch": "",
"autodeploy": false,
"busy": null,
"queued": false,
"last_deployment": {"id": 7, "status": "success", "title": "Deploy", "finished": 1790460640, "...": "..."},
"status": {
"state": "running",
"running": true,
@ -136,20 +197,20 @@ same app returns `409` with `{"ok": false, "error": "...", "busy": "deploy"}`.
{
"name": "whoami",
"routes": [
{"domain": "whoami.reudy.net", "upstream": "127.0.0.1:18080"}
{"domain": "whoami.reudy.net", "target": "80"}
],
"auth": true
}
```
### Create app (multiple routes, different ports)
### Create app (multiple routes, different services)
```json
{
"name": "myapp",
"routes": [
{"domain": "app.reudy.net", "upstream": "127.0.0.1:18080"},
{"domain": "api.app.reudy.net", "upstream": "127.0.0.1:18081"}
{"domain": "app.reudy.net", "target": "web:3000"},
{"domain": "api.app.reudy.net", "target": "api:8080"}
],
"auth": true
}