RustUse/use-docker

use-docker is a RustUse facade workspace for primitive Docker vocabulary: Dockerfile instruction fragments, .dockerignore rules, image references, tags, registries, Compose-shaped data, ports, volumes, networks, environment files, healthchecks, labels, and build metadata.

This is not a Docker engine, Docker client, container runtime, registry client, Compose implementation, image builder, or command runner. The first release wave is intentionally small: parsers, validators, normalized types, builders, and rendering helpers that do not shell out or make network calls.

Workspace Crates

Crate	Path	Purpose
use-docker	crates/use-docker/	Feature-gated facade over the focused Docker primitive crates
use-dockerfile	crates/use-dockerfile/	Dockerfile instruction line primitives and rendering helpers
use-dockerignore	crates/use-dockerignore/	.dockerignore line and pattern classification
use-docker-image	crates/use-docker-image/	Docker image reference parsing and component accessors
use-docker-tag	crates/use-docker-tag/	Docker tag validation, normalization, and classification
use-docker-registry	crates/use-docker-registry/	Registry host and repository path primitives
use-docker-compose	crates/use-docker-compose/	Lightweight Docker Compose data model primitives
use-docker-port	crates/use-docker-port/	Port mapping parsing and rendering
use-docker-volume	crates/use-docker-volume/	Volume and mount syntax primitives
use-docker-network	crates/use-docker-network/	Network mode and named network primitives
use-docker-env	crates/use-docker-env/	Environment variable and env-file line primitives
use-docker-healthcheck	crates/use-docker-healthcheck/	Healthcheck command and timing primitives
use-docker-label	crates/use-docker-label/	Docker and OCI label key/value primitives
use-docker-build	crates/use-docker-build/	Build context, build arg, target, platform, and cache primitives

Installation

Use the workspace directly or depend on a Git revision until the first crates.io release is published.

[dependencies]
use-docker = { git = "https://github.com/RustUse/use-docker", rev = "<commit>" }

After publication, choose the narrowest crate that matches your use case or use the facade when one dependency is more convenient.

[dependencies]
use-docker = "0.0.1"

Basic Usage

#[cfg(feature = "full")]
{
use use_docker::{compose, dockerfile, env, image, port};

let image_ref: image::DockerImageReference = "ghcr.io/rustuse/app:0.1.0".parse()?;
let mapping: port::PortMapping = "127.0.0.1:8080:80/tcp".parse()?;
let variable = env::EnvLine::parse("RUST_LOG=info")?;
let service = compose::ComposeService::new("web")
    .with_image(image_ref.as_str())
    .with_port(mapping.to_string());
let instruction = dockerfile::DockerfileInstruction::run("cargo test");

assert_eq!(image_ref.registry(), Some("ghcr.io"));
assert_eq!(variable.key(), Some("RUST_LOG"));
assert_eq!(service.name(), "web");
assert_eq!(instruction.to_string(), "RUN cargo test");
}
# Ok::<(), Box<dyn std::error::Error>>(())

Scope

• Small, dependency-light Rust primitives for Docker-related text and metadata.
• Conservative validation for common image names, tags, ports, labels, and env keys.
• Typed data models that are useful before choosing a larger Docker or YAML stack.
• Facade access through use-docker plus narrow focused crates for direct use.

Non-Goals

• No Docker CLI execution.
• No Docker socket or Docker engine API client.
• No image build, pull, push, run, inspect, or container lifecycle behavior.
• No live registry HTTP API calls in v0.1.
• No full Dockerfile parser or evaluator.
• No full Docker Compose implementation or YAML parser in v0.1.
• No filesystem walking or ignore-rule matching engine.

Experimental

use-docker is experimental while the workspace remains below 0.3.0. Expect small API adjustments during the first release wave.

Development

cargo fmt --all -- --check
cargo check --workspace --all-features
cargo check --workspace --all-features --examples
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features
cargo test --workspace --no-default-features

License

Licensed under either of the following, at your option:

• Apache License, Version 2.0
• MIT license