Crate ociman

Crate ociman 

Source
Expand description

§ociman - OCI Manager

A Rust library providing a unified API for OCI container runtimes (Docker, Podman).

§⚠️ Status

ociman is highly unstable and exists solely to serve pg-ephemeral. The API is changing frequently and nothing should be considered stable. Breaking changes occur without notice as the library evolves to meet pg-ephemeral’s needs.

Do not use this library for other projects at this time.

§Goals

  • Unified API: Single interface for OCI-compliant container runtimes
  • Auto-detection: Automatically detects available container runtime
  • Environment override: Control backend selection via OCIMAN_BACKEND environment variable
  • Container lifecycle management: Run, execute commands, inspect, and manage containers
  • Image building: Build images from Dockerfiles or inline instructions
  • Content-based hashing: Automatic tag generation based on SHA256 of build context/instructions for deterministic builds

§Content-Based Image Hashing

ociman supports automatic tag generation based on content hashing (SHA256). This ensures deterministic builds where the same content always produces the same image tag.

Benefits:

  • Deterministic: Same content always produces the same tag
  • Automatic cache invalidation: Content changes automatically produce a new tag
  • No manual tag management: Hash is computed automatically
  • Reproducibility: Easy to verify if an image matches its source

Important: Content-based hashing only captures the Dockerfile and build context, not the base images. Using unspecific tags like FROM alpine:latest reduces reproducibility since latest can point to different images over time. For fully reproducible builds, use specific base image digests:

# Less reproducible - tag can change
FROM alpine:latest

# More reproducible - specific version tag
FROM alpine:3.19

# Most reproducible - pinned to specific digest
FROM alpine@sha256:6457d53fb065d6f250e1504b9bc42d5b6c65941d57532c072d929dd0628977d0

§License

See workspace root for license information.

Re-exports§

pub use backend::Backend;
pub use backend::ContainerHostnameResolver;
pub use backend::ResolveHostnameError;
pub use command::Command;
pub use image::BuildArgumentKey;
pub use image::BuildArgumentKeyError;
pub use image::BuildArgumentValue;
pub use image::BuildDefinition;
pub use image::BuildSource;
pub use image::BuildTarget;
pub use image::Reference;

Modules§

backend
command
image
OCI image reference and build utilities.
platform
Platform support detection for container-based tools
reference
OCI image reference parsing and types.
testing
Testing utilities for container-based tests

Macros§

test_backend_setup

Structs§

Container
ContainerArgument
ContainerId
Definition
Entrypoint
EnvironmentVariables
ExecCommand
Builder for executing commands inside a container.
Mount
Publish
Port publishing configuration for container networking.
Workdir

Enums§

Detach
Protocol
Remove