Use the system
systemd already supervises, restarts, logs and schedules. PodHull describes what to run and lets it do that job.
Architecture
Small parts.
Clear boundaries.
PodHull is three Go programs and the tools your distribution already ships. Nothing runs as root that does not have to, and nothing reaches an application that it did not ask for.
Edge
podhull-proxy
Listens on 80 and 443 through systemd sockets. Terminates TLS, holds ACME certificates and forwards each domain to its service or to the panel.
Control
podhull-panel
The web interface and JSON API. Runs as its own unprivileged user, signs people in with their keys, keeps state in plain files and records every change.
Privilege
podhull-agent
The only part that runs as root, started on demand by podhull-agent.socket. It accepts a short list of operations from the panel and validates every unit before it writes anything.
System
systemd · Quadlet · Podman
Each application has its own Linux user. Its services are Quadlet units run by that user's systemd, as rootless Podman containers.
Apps
user ph-a1…user ph-b2…user ph-c3…user ph-d4…
A deploy, step by step
What happens when you press Deploy.
- 1
The panel checks the request
A valid session, the CSRF token and, for sensitive actions, a fresh signature with your key. The request is written to the audit log.
- 2
A unit is generated
The panel turns the service settings into a Quadlet unit. You never send unit text from the browser unless you edit the unit file on purpose.
- 3
The agent validates it
Over its Unix socket, the agent checks the unit against the allow-lists of
podhull-protocol, the same code the panel uses. Anything outside them is refused. - 4
systemd starts the new version
The unit is written for the application's user and started by that user's systemd as a rootless container, beside the version that still serves traffic.
- 5
Traffic moves when it is healthy
Once the health check passes, the route moves to the new instance and the old one stops. If it fails, the old one keeps serving.
Design principles
Choices we made on purpose.
Keep it running without us
Stop the panel and every application keeps running. The units are ordinary files you can read with systemctl.
Few dependencies
The Go standard library and golang.org/x only. The interface is plain ES modules with a strict Content Security Policy and nothing loaded from elsewhere.
Plain files for state
No database server to run, tune or back up. State is JSON on disk, written atomically.
One server, done well
PodHull does not try to be a cluster. It aims to make a single machine as pleasant and safe as a managed platform.
Specified first
Behaviour is written down in a public specification with numbered requirements, and the tests refer to them.
On disk
Where everything lives.
Every path is standard, so the tools you already use for your servers keep working.
/usr/libexec/podhull/the three binaries/etc/podhull/panel.jsoninstallation settings/var/lib/podhull/panel state, keys and audit logpodhull-*.service / .socketthe platform's own systemd unitsuser ph-…one per application, with its units, images and volumesjournalctlevery log, platform and applications alike