Getting Started
Last updated
This page walks through building, configuring, and running your first
podrun up to deploy a compose project to remote Podman.Prerequisites
| Requirement | Where | Notes |
|---|---|---|
| Go 1.25.1+ | Build host | Taken from go.mod |
C compiler (CGO_ENABLED=1) | Build host (API server) | github.com/mattn/go-sqlite3 requires cgo |
sshpass, rsync, ssh, curl, unzip | Local (CLI) | CheckRelyPackages() installs them when missing |
| macOS or Linux | Local (CLI) | Other operating systems abort when packages are missing |
| SSH password login | Remote host | The CLI connects through sshpass |
Podman + podman compose | Remote host | Container runtime |
rsync | Remote host | rsync over SSH runs on both ends |
Write access to /home/podrun | Remote host | Remote project folders are always created here |
Installation
- git clone https://github.com/pardnchiu/PodRun.git
- cd PodRun
- go build -o podrun ./cmd/cli
- CGO_ENABLED=1 go build -o podrun-api ./cmd/api
For the CLI alone, use
go install; the resulting binary is named cli after the package directory:- go install github.com/pardnchiu/PodRun/cmd/cli@latest
Configure the Remote Connection
On startup the CLI reads three required variables from
.env in the current working directory and aborts if any is missing:- PODRUN_SERVER=192.168.1.100
- PODRUN_USERNAME=podrun
- PODRUN_PASSWORD=yourpassword
See Configuration for every variable.
Start the API Server
The API server reads
sql/create.sql through a relative path, so run it from the repo root. The CLI always targets localhost:8080, so both must run on the same machine.- cd PodRun
- ./podrun-api
First Deployment
Run inside a project folder that contains
docker-compose.yml or docker-compose.yaml:- cd ~/projects/my-app
- podrun up -d
In
-d mode the command prints container port mappings, the Pod ID and name, and the local hostname and IP. Day-to-day commands:- podrun ps
- podrun logs -f
- podrun down
- podrun clear
Next Steps
- Core Concepts: how the UID and remote folder are derived
- File Sync: diff preview and exclude rules
- CLI Reference: every command and flag