95 lines
2.5 KiB
Markdown
95 lines
2.5 KiB
Markdown
# podman
|
|
|
|
A Dart client for the Podman **libpod API** over the Podman socket.
|
|
|
|
This package uses HTTP over Unix sockets and targets libpod endpoints directly,
|
|
without shelling out to the `podman` CLI.
|
|
|
|
## Features
|
|
|
|
- Typed `PodmanClient` API for system, container, and image operations
|
|
- Network lifecycle and connect/disconnect APIs
|
|
- Network exists/update/prune APIs
|
|
- Volume lifecycle APIs
|
|
- Pod lifecycle APIs
|
|
- Pod exists/admin/top/stats/prune APIs
|
|
- Container runtime helpers (`wait`, `healthStatus`, `exec`, `stats`)
|
|
- Container admin APIs (kill/pause/unpause/top/init/rename/update/mount/archive)
|
|
- Container checkpoint/restore APIs (including archive export/import helpers)
|
|
- System maintenance APIs (`system/df`, `system/check`, `system/prune`)
|
|
- Typed events API with reconnecting watch stream
|
|
- Unix-socket transport (`UnixSocketPodmanTransport`)
|
|
- Libpod API-first implementation (no Docker-compat fallback path)
|
|
- Focused option and model types
|
|
- Testable transport abstraction for deterministic unit tests
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
dart pub add podman
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```dart
|
|
import 'package:podman/podman.dart';
|
|
|
|
Future<void> main() async {
|
|
final client = PodmanClient();
|
|
final version = await client.version();
|
|
print('Podman server: ${version.serverVersion}');
|
|
await client.close();
|
|
}
|
|
```
|
|
|
|
## Socket Resolution
|
|
|
|
By default, the transport resolves socket path in this order:
|
|
|
|
1. `PODMAN_SOCKET`
|
|
2. `$XDG_RUNTIME_DIR/podman/podman.sock`
|
|
3. `/run/user/$UID/podman/podman.sock`
|
|
4. `/run/podman/podman.sock`
|
|
|
|
You can override via:
|
|
|
|
```dart
|
|
final client = PodmanClient(socketPath: '/custom/path/podman.sock');
|
|
```
|
|
|
|
## Examples
|
|
|
|
- `example/version_info_example.dart`
|
|
- `example/list_containers_example.dart`
|
|
- `example/pull_and_run_example.dart`
|
|
- `example/inspect_container_example.dart`
|
|
- `example/secrets_workflow_example.dart`
|
|
- `example/manifest_workflow_example.dart`
|
|
- `example/artifact_workflow_example.dart`
|
|
- `example/generate_assets_example.dart`
|
|
- `example/play_kube_file_example.dart`
|
|
- `example/system_maintenance_example.dart`
|
|
- `example/checkpoint_restore_example.dart`
|
|
|
|
Copy/paste command guide:
|
|
|
|
- `doc/examples.md`
|
|
|
|
## Testing Backends
|
|
|
|
Default tests use a fake transport for deterministic unit coverage:
|
|
|
|
```bash
|
|
melos run test
|
|
```
|
|
|
|
Local integration tests can run against your local Podman socket:
|
|
|
|
```bash
|
|
melos run test:integration
|
|
```
|
|
|
|
Optional env vars:
|
|
|
|
- `PODMAN_TEST_SOCKET`: override socket path for local tests
|
|
- `PODMAN_LOCAL_TESTS=1`: alternate way to enable local tests
|