v0.11.0

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
  1. graph LR
  2. subgraph Local Host
  3. CLI["podrun CLI (cmd/cli)"]
  4. API["API Server (cmd/api :8080)"]
  5. DB[(SQLite)]
  6. end
  7. subgraph Remote Host
  8. Dir[/home/podrun/name_hash/]
  9. Compose[Podman Compose]
  10. K3s[k3s unfinished]
  11. end
  12. CLI -->|rsync over sshpass| Dir
  13. CLI -->|ssh commands| Compose
  14. CLI -.->|unfinished| K3s
  15. Compose --> Dir
  16. CLI -->|HTTP POST| API
  17. API --> DB

Layers


LayerPackageResponsibility
Entrycmd/cliLoad .env, check dependencies and env vars, test SSH, dispatch the command
Entrycmd/apiResolve DB_PATH, open SQLite, start the HTTP server
Commandinternal/commandParse arguments, derive local and remote paths, run up / clear / passthrough commands, report to the API
Utilitiesinternal/utilssshpass wrappers (SSHRun, SSEOutput, SSHTest), dependency install, local MAC / IP / hostname
HTTPinternal/handlerGin routes and JSON binding
Storageinternal/databaseUpsert, update, insert, and list for pods / records
Modelinternal/modelPod, Record, User structs

Cross-Cutting Principles


  • No PodRun agent on the remote host: the remote host needs SSH, rsync, and Podman with podman 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() and recordPod() are ignored; only the final upsertPod() in up returns an error


ToolWhat it isHow PodRun relates
docker contextDocker CLI setting that points commands at another Docker daemonPodRun copies the project to the remote host first and runs Podman there; see File Sync
containers/podman-composePython script that runs docker-compose.yml using PodmanPodRun calls podman compose on the remote host over SSH; podman compose hands the file to an installed compose provider such as podman-compose
basecamp/kamalRuby CLI that deploys Docker containers over SSH, configured in config/deploy.ymlPodRun 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/dcdRust CLI that syncs files and manages Docker Compose services over SSHSame 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 SSHPodRun is a standalone Go CLI that works on any compose project, with no application framework involved
sprisa/composureGo CLI that ships docker-compose services to multiple servers via SSHPodRun 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.
中文