provisioning-platform/prov-ecosystem/crates/runtime

Runtime - Container Runtime Abstraction

A unified abstraction layer for managing multiple container runtimes with automatic detection and platform-aware selection.

Overview

Runtime provides a unified API for working with different container runtimes:

• 🐳 Docker - Industry standard container runtime
• 🐋 Podman - Open-source Docker alternative with rootless support
• 🪨 OrbStack - Fast macOS Docker alternative (default on macOS)
• 🎨 Colima - Another macOS Docker alternative
• 📦 nerdctl - containerd CLI tool

Features

• 🔄 Unified API - Same interface for all runtimes
• 🎯 Auto-Detection - Detect available runtimes with platform awareness
• 🔌 Remote Support - SSH-based access to remote runtimes
• 🐳 Compose Support - Docker Compose file handling
• 🔧 Configuration - Flexible runtime configuration
• ⚡ Platform-Aware - Intelligent defaults per OS/platform

Supported Runtimes

Docker

Industry-standard container runtime

use runtime::RuntimeType;

let runtime = RuntimeType::Docker;
// Socket: /var/run/docker.sock
// Compose: docker compose

Podman

Docker-compatible with rootless support

let runtime = RuntimeType::Podman;
// Socket: $XDG_RUNTIME_DIR/podman/podman.sock
// Compose: podman-compose

OrbStack

Fast Docker alternative for macOS (default on macOS)

let runtime = RuntimeType::OrbStack;
// Socket: ~/.orbstack/run/docker.sock
// Compose: docker compose

Colima

Another macOS Docker alternative

let runtime = RuntimeType::Colima;
// Socket: ~/.colima/docker.sock
// Compose: docker compose

nerdctl

containerd CLI tool

let runtime = RuntimeType::Nerdctl;
// Socket: unix:///run/containerd/containerd.sock
// Compose: nerdctl compose

Quick Start

use runtime::{detect_runtime, RuntimeConfig};

// Auto-detect available runtime
let runtime = detect_runtime().await?;
println!("Using: {}", runtime.name());

// Or create configuration manually
let config = RuntimeConfig {
    runtime: RuntimeType::Docker,
    socket_path: "/var/run/docker.sock".to_string(),
    ..Default::default()
};

let runtime = Runtime::new(config);
let info = runtime.info().await?;
println!("Version: {}", info.version);

Detection Priority

macOS

1. OrbStack (fastest native integration)
2. Docker Desktop
3. Colima
4. Podman
5. nerdctl

Linux

1. Docker
2. Podman (rootless)
3. nerdctl
4. Colima
5. OrbStack

Remote Runtime Access

Connect to remote runtimes via SSH:

use runtime::{RuntimeConfig, RemoteConfig};

let remote = RemoteConfig {
    enabled: true,
    host: "docker.example.com".to_string(),
    user: "docker-user".to_string(),
    private_key: Some("/home/user/.ssh/id_rsa".to_string()),
    ..Default::default()
};

let config = RuntimeConfig {
    remote_config: Some(remote),
    ..Default::default()
};

Docker Compose Support

Adapt Docker Compose files for different runtimes:

use runtime::adapt_compose;

let adapted = adapt_compose(
    "docker-compose.yaml",
    RuntimeType::Podman
).await?;

println!("Adapted compose: {}", adapted);

Configuration

Environment Variables

let config = RuntimeConfig {
    environment: [
        ("DOCKER_HOST", "unix:///var/run/docker.sock"),
        ("DOCKER_TLS_VERIFY", "1"),
    ].iter().cloned().collect(),
    ..Default::default()
};

Socket Paths

let config = RuntimeConfig {
    socket_path: "/var/run/docker.sock".to_string(),
    ..Default::default()
};

Command Flags

let config = RuntimeConfig {
    flags: vec![
        "--tlsverify".to_string(),
        "--tlscacert=/path/to/ca.pem".to_string(),
    ],
    ..Default::default()
};

Architecture

• error.rs - Error types for runtime operations
• runtime_type.rs - RuntimeType enum with socket paths
• config.rs - Configuration structures
• detect.rs - Async runtime detection
• compose.rs - Docker Compose adaptation
• runtime.rs - Main runtime abstraction

Use Cases

Container Orchestration

Manage containers across different runtimes

CI/CD Integration

Build and run containers in pipelines

Local Development

Detect and use available runtime on developer machines

Multi-Cloud Deployments

Support different runtimes in different environments

Rootless Execution

Use Podman for non-root container execution

Compatibility Matrix

Operation	Docker	Podman	OrbStack	Colima	nerdctl
build	✅	✅	✅	✅	✅
run	✅	✅	✅	✅	✅
compose	✅	✅	✅	✅	✅
push	✅	✅	✅	✅	✅
pull	✅	✅	✅	✅	✅

Testing

Run tests with:

cargo test --lib

All 24 tests pass with full coverage of:

• Runtime detection
• Configuration management
• Socket path handling
• Compose adaptation
• Remote configuration

Performance

• Fast runtime detection
• Minimal overhead
• Efficient socket communication
• Low memory footprint

API Documentation

Full API documentation available with:

cargo doc --open

Integration

Runtime can be integrated with:

• Container orchestration systems
• CI/CD pipelines
• Deployment automation (provctl, provisioning)
• Development tools
• Infrastructure management

Platform Support

• ✅ Linux (all architectures)
• ✅ macOS (Intel and Apple Silicon)
• ✅ Windows (with WSL2)
• ✅ Remote servers (SSH)

License

Same as prov-ecosystem parent project

Contributing

Contributions welcome! See parent project guidelines.

See Also

• prov-ecosystem README - Parent project overview
• valida - Validation rules engine
• encrypt - Multi-backend encryption
• init-servs - Init system abstraction