podman/doc/examples.md

podman examples quickstart

This guide provides copy/paste commands for each example in packages/podman/example.

Prerequisites

Run from package directory:

cd /home/artificer/Projects/groupware/packages/podman

Ensure Podman API socket is available (optional override):

export PODMAN_SOCKET="${PODMAN_SOCKET:-$XDG_RUNTIME_DIR/podman/podman.sock}"

Command Matrix

Example	Purpose	Command
version_info_example.dart	Show Podman version and host info	dart run example/version_info_example.dart
list_containers_example.dart	List local containers	dart run example/list_containers_example.dart
pull_and_run_example.dart	Pull and run hello-world	dart run example/pull_and_run_example.dart
inspect_container_example.dart	Inspect one container	dart run example/inspect_container_example.dart <container-name-or-id>
secrets_workflow_example.dart	Create/inspect/list/remove a secret	PODMAN_EXAMPLE_SECRET='change-me' dart run example/secrets_workflow_example.dart --name=gw-jwt --replace --show-secret --cleanup
manifest_workflow_example.dart	Create/inspect/push/delete a manifest list	dart run example/manifest_workflow_example.dart groupware-stack quay.io/groupware/api:amd64 quay.io/groupware/api:arm64 --push=quay.io/groupware/api:latest --cleanup
artifact_workflow_example.dart	Pull/inspect/list/push/remove OCI artifact	dart run example/artifact_workflow_example.dart quay.io/groupware/policy:latest --push --cleanup=batch
generate_assets_example.dart	Generate kube YAML and systemd units	dart run example/generate_assets_example.dart groupware-orchestrator --kube-out=./generated/stack.yaml --systemd-dir=./generated/systemd
play_kube_file_example.dart	Apply or tear down kube YAML through Podman	dart run example/play_kube_file_example.dart ./generated/stack.yaml --replace
system_maintenance_example.dart	Disk usage + optional check/prune	dart run example/system_maintenance_example.dart --check --quick
checkpoint_restore_example.dart	Checkpoint/export/restore flows	dart run example/checkpoint_restore_example.dart checkpoint groupware-orchestrator --print-stats

Additional Checkpoint/Restore Commands

# Export checkpoint archive
dart run example/checkpoint_restore_example.dart export groupware-orchestrator ./generated/orchestrator-checkpoint.tar

# Restore from container checkpoint state
dart run example/checkpoint_restore_example.dart restore groupware-orchestrator --print-stats

# Restore from archive
dart run example/checkpoint_restore_example.dart restore-archive ./generated/orchestrator-checkpoint.tar --name=orchestrator-restored

Safer Maintenance Commands

# Read-only usage snapshot
dart run example/system_maintenance_example.dart

# Consistency checks only
dart run example/system_maintenance_example.dart --check --quick --max-age=24h

# Destructive prune (requires --yes)
dart run example/system_maintenance_example.dart --prune --all --volumes --yes