v0.11.0

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:
PrioritySource
1--folder=<path> or --folder <path>
2Whichever comes first in the arguments: the directory of -f <file> (when dir != ".") or a positional directory that starts with ./ or / and exists
3Current working directory

The folder must exist and contain docker-compose.yml or docker-compose.yaml; otherwise command.New() returns an error.

Deployment UID


  1. 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


  1. /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


CommandPathBehavior
upup()Sync, rewrite compose, recreate containers, report to the API
clearclear()Remove containers, volumes, images, and the remote folder
down / ps / logs / restart / exec / buildrunCMD()Run podman compose <args> in the remote folder
domain / deploymainNo 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: up streams compose output in the foreground; the remote command is wrapped in trap cleanup INT TERM, so Ctrl+C runs podman compose down
中文