Core Concepts
Last updated
This page explains how PodRun identifies a deployment: the rules for the UID, the remote folder, and the local project folder.
Local Project Folder
Resolved in this order, then converted to an absolute path:
| Priority | Source |
|---|---|
| 1 | --folder=<path> or --folder <path> |
| 2 | Whichever comes first in the arguments: the directory of -f <file> (when dir != ".") or a positional directory that starts with ./ or / and exists |
| 3 | Current working directory |
The folder must exist and contain
docker-compose.yml or docker-compose.yaml; otherwise command.New() returns an error.Deployment UID
- uid = md5("<MAC>@<local-absolute-path>")
- The MAC comes from the first non-loopback interface with a hardware address; the hostname is used when none is found
- The same machine and project path always yield the same UID
-u <uid>overrides it; the override affects only the recorded UID, not the remote folder
Remote Folder
- /home/podrun/<local-folder-name>_<first-8-hash-chars>
The hash shares its source with the UID, so same-named projects from different machines or paths never overwrite each other. The
/home/podrun root is fixed and independent of PODRUN_USERNAME.Command Dispatch
| Command | Path | Behavior |
|---|---|---|
up | up() | Sync, rewrite compose, recreate containers, report to the API |
clear | clear() | Remove containers, volumes, images, and the remote folder |
down / ps / logs / restart / exec / build | runCMD() | Run podman compose <args> in the remote folder |
domain / deploy | main | No action (unfinished) |
| Anything else | — | unsupported command |
The first element of
RemoteArgs is the command name; -d, -f <file-name>, and other arguments are forwarded to podman compose as-is.Foreground and Background
-d: containers start in the background, then port mappings and Pod info are printed- Without
-d:upstreams compose output in the foreground; the remote command is wrapped intrap cleanup INT TERM, so Ctrl+C runspodman compose down