Architecture
Last updated
This page uses a single overview diagram to show how the PodRun CLI, the remote host, and the API server relate.
System Overview
graph LR
subgraph Local Host
CLI["podrun CLI (cmd/cli)"]
API["API Server (cmd/api :8080)"]
DB[(SQLite)]
end
subgraph Remote Host
Dir[/home/podrun/name_hash/]
Compose[Podman Compose]
K3s[k3s unfinished]
end
CLI -->|rsync over sshpass| Dir
CLI -->|ssh commands| Compose
CLI -.->|unfinished| K3s
Compose --> Dir
CLI -->|HTTP POST| API
API --> DB- graph LR
- subgraph Local Host
- CLI["podrun CLI (cmd/cli)"]
- API["API Server (cmd/api :8080)"]
- DB[(SQLite)]
- end
- subgraph Remote Host
- Dir[/home/podrun/name_hash/]
- Compose[Podman Compose]
- K3s[k3s unfinished]
- end
- CLI -->|rsync over sshpass| Dir
- CLI -->|ssh commands| Compose
- CLI -.->|unfinished| K3s
- Compose --> Dir
- CLI -->|HTTP POST| API
- API --> DB
Layers
| Layer | Package | Responsibility |
|---|---|---|
| Entry | cmd/cli | Load .env, check dependencies and env vars, test SSH, dispatch the command |
| Entry | cmd/api | Resolve DB_PATH, open SQLite, start the HTTP server |
| Command | internal/command | Parse arguments, derive local and remote paths, run up / clear / passthrough commands, report to the API |
| Utilities | internal/utils | sshpass wrappers (SSHRun, SSEOutput, SSHTest), dependency install, local MAC / IP / hostname |
| HTTP | internal/handler | Gin routes and JSON binding |
| Storage | internal/database | Upsert, update, insert, and list for pods / records |
| Model | internal/model | Pod, Record, User structs |
Cross-Cutting Principles
- No PodRun agent on the remote host: the remote host needs SSH,
rsync, and Podman withpodman compose; all logic runs in the local CLI through SSH commands - Original files untouched: the local compose file is never modified; rewriting happens only in the remote copy
docker-compose.podrun.yml - Record failures never block deploys: errors from
removePod()andrecordPod()are ignored; only the finalupsertPod()inupreturns an error
Related Tools
| Tool | What it is | How PodRun relates |
|---|---|---|
docker context | Docker CLI setting that points commands at another Docker daemon | PodRun copies the project to the remote host first and runs Podman there; see File Sync |
| containers/podman-compose | Python script that runs docker-compose.yml using Podman | PodRun calls podman compose on the remote host over SSH; podman compose hands the file to an installed compose provider such as podman-compose |
| basecamp/kamal | Ruby CLI that deploys Docker containers over SSH, configured in config/deploy.yml | PodRun reads your existing docker-compose.yml and targets Podman; up runs down -v before starting, so it does not keep the old containers running during a deploy |
| g1ibby/dcd | Rust CLI that syncs files and manages Docker Compose services over SSH | Same SSH-and-sync shape; PodRun runs podman compose on a rewritten copy with host ports stripped and :z added to relative volumes |
| davidfowl/aspire-ssh-deploy | .NET Aspire extension of the docker compose integration that deploys to a Docker host via SSH | PodRun is a standalone Go CLI that works on any compose project, with no application framework involved |
| sprisa/composure | Go CLI that ships docker-compose services to multiple servers via SSH | PodRun deploys to the one host set in PODRUN_SERVER and reports every operation to its local API server (Deployment Records) |
Further Reading
Per-module diagrams, the
up sequence diagram, and the state machine live in doc/architecture.md.