# podman examples quickstart

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

## Prerequisites

Run from package directory:

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

Ensure Podman API socket is available (optional override):

```bash
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

```bash
# 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

```bash
# 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
```