Generated files

Project files: .portler/

Portler writes runtime files to .portler/ in the project directory:

.portler/setup.json          receipts of the plain setup steps that succeeded, per owner and mode
.portler/state.json          last assignments and run metadata
.portler/runtime.env         resolved env snapshot
.portler/pids.json           pids of detached services and the proxy, and how each was launched
.portler/logs/<service>.log  captured output of detached local services
.portler/k8s/                generated Kubernetes manifests
.portler/k8s-context.json    the kubectl context and namespace "up k8s" deployed to, used by env and "down k8s"

These files should not be committed:

.portler/

Notes:

• Runtime files carry the absolute project identity. Do not copy .portler/ into another checkout: Portler rejects a state/PID file whose project does not match the current directory, so a copied checkout can never signal the original checkout's recorded processes.
• Log files are written for services started with portler up -d, truncated on each restart, and kept after portler down for post-mortem inspection.
• portler clean removes the whole .portler/ directory (refusing while services run, unless --force).
• .portler/k8s/ is regenerated by portler up k8s and portler k8s render.

Global files: ~/.portler/

~/.portler/ports.json        global port registry (all projects on this machine)
~/.portler/ports.lock        lock file serializing port allocation

The registry records which project/service reserved which port and bind host, so concurrent portler up runs in different projects never hand out the same port. Stale entries (port free again on the recorded host, reservation more than five minutes old) are pruned automatically; portler clean --global forces a prune, and portler clean --ports releases the current project's reservations. If the registry itself is malformed, ordinary commands fail closed rather than discard unknown reservations; portler clean --global --force is the explicit reset path.

Setup receipts

setup.json stores version 2, the absolute project identity, and per owner (keyed by run mode local/docker, environment dev/prod, and project or service:<name>) the SHA-256 fingerprints of the plain setup steps that succeeded. A fingerprint covers one step's command, resolved cwd and mode, the content of its watch files if it has any, plus its position among the entries of its list that run the same command, whatever their kind, and how many such entries there are, so adding or removing a duplicate of a command runs every entry with that command again. A receipt is written as soon as its step succeeds; a step that left its definition loses its receipt before the next run in that mode, whether or not its owner is part of that run, and an owner that left the config (or has no steps left in that mode) loses all of them the same way, and a forced run clears every receipt of the owner before running. if_missing and always steps never get one. Writes are atomic and serialized by the lifecycle lock. Receipts copied from another checkout are not reused, and a version 1 file (one fingerprint per owner) is treated as empty.

Deleting this file (or running clean) makes the next up run every plain step again. down preserves receipts. Source files, lockfiles, env values and port assignments are not fingerprinted unless a step lists files in watch; otherwise use if_missing or always steps, or force setup, when these inputs require a rerun.