coopr

package module
v0.0.0-...-7daf44e Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: MIT Imports: 18 Imported by: 0

README

Coopr

Coopr builds OCI container images from ordered KDL definitions. Share build steps and files through reusable components, using local definitions or packaged OCI artifacts.

Install

curl -fsSL https://coopr.strio.dev/install.sh | sh
coopr --version

See getting started for Linux prerequisites and other installation options.

Hello, world

Save this as components/greeting.coopr:

from "docker.io/redhat/ubi9:latest" as="builder" {
    run "echo 'Hello, world!' > /hello.txt"
}
package as="greeting" {
    copy "/hello.txt" "/hello.txt" from="builder"
}
extend {
    copy "/hello.txt" "/hello.txt" from="greeting"
}

The component generates a greeting, packages the file, and copies it into the calling image. Save the caller as image.coopr:

from "docker.io/redhat/ubi9:latest" {
    component "./components/greeting.coopr"
    cmd {
        exec "cat" "/hello.txt"
    }
}

Build and run it with Podman:

coopr build --file image.coopr --tag hello:latest .
podman run --rm localhost/hello:latest

The container prints:

Hello, world!

Run Coopr and Podman as the same user with the same storage settings. The first-image tutorial explains each step and shows how changes affect the cache.

Reuse build steps

Apply a shared definition with component "./components/shared.coopr". Share a local component between two images without a separate packaging command or registry.

For components you can distribute, follow the reusable-components tutorial to package two components and apply them to an image. Explore the examples for cache mounts and published components, or read about image storage and transfers.

Build from an application

Use the Go execution library to run builds in your application. To keep the native engine in a separate process, start a local service and call it with the Go client. The client can submit typed programs, build images and components, and transfer artifacts.

Development

Development uses the pinned Nix environment. See contributing for source builds, tests, and documentation checks.

Coopr is licensed under the MIT License.

Documentation

Overview

Package coopr executes typed build programs through Coopr's supervised native Buildah backend. Applications must call InitReexec at the start of main before parsing arguments. Workers reexecute that same binary and enter rootless user namespaces themselves; the host application need not enter a user namespace.

Execution requires Linux, configured subordinate IDs/rootless namespaces, containers/storage support and an OCI runtime when running commands. Host or nested-container policy may prevent execution. Callers own store/cache roots, input contexts and successful output paths. Execute owns disposable workers and staging directories and drains cancellation cleanup. ErrCleanupFailed means completion could not be confirmed; callers must retain borrowed inputs and directories containing retained staging while investigating that failure.

Index

Constants

This section is empty.

Variables

ErrCleanupFailed means worker cleanup failed or could not be confirmed. Check with errors.Is even when the error also reports context cancellation. Keep borrowed inputs and retained staging available until cleanup is resolved.

Functions

func InitReexec

func InitReexec() bool

InitReexec dispatches registered same-binary build workers and runtime helpers. Call first in main, and return immediately when it returns true.

Dispatch runs before application argument checks, following Buildah's embedding contract. It does not authenticate application requests. Do not expose the executable through setuid, file capabilities or restricted sudo rules that rely on those later checks to limit the caller's operations. Operator-authorized root and sudo builds use the operator's existing authority.

Types

type CacheOptions

type CacheOptions struct {
	// MountDir selects the private persistent parent for native RUN cache mounts.
	// Contents are disposable acceleration and are not hashed into build inputs.
	MountDir     string
	LocalDir     string
	NoCache      bool
	RegistryFrom []string
	RegistryTo   []string
}

CacheOptions controls the optional portable instruction cache. LocalDir is a caller-owned absolute OCI cache directory. RegistryFrom and RegistryTo select bare registry repositories for reads and writes independently; they may be combined with LocalDir. Leaving all locations empty disables portable caching. Native local Buildah layer reuse is separate and is not counted by CacheStats.

type CacheStats

type CacheStats struct{ Hits, Misses, Stored, Skipped, Errors int }

CacheStats counts optional portable-cache decisions, not total backend reuse.

type Copy

type Copy struct {
	Sources     []string
	Destination string
	From        Source
}

Copy copies Sources into Destination from an image, state or host context.

type Env

type Env struct{ Name, Value string }

Env sets one literal image environment value inherited by later commands.

type Mount

type Mount struct {
	// HostPath is an explicit live host directory for one bind RUN mount.
	// It is exclusive with From and Source. Live mounts bypass result caching;
	// ordinary context mounts retain their snapshotted semantics.
	HostPath string
	// Relabel explicitly opts a live host directory into native SELinux z/Z relabeling.
	Relabel                           string
	Type, Target, Source, ID, Sharing string
	From                              Source
	ReadOnly                          bool
}

Mount is a bind, cache or tmpfs RUN mount. Omitted cache IDs use native stable program/platform/stage scope. Sharing is shared or locked; the current Buildah backend does not implement private sharing. From applies only to bind mounts. ReadOnly false requests writable binds. Writable host-context binds use the native disposable build-scoped context copy and side-effect-aware cache; the caller context is preserved. Other mount types retain native defaults when ReadOnly is false.

type Operation

type Operation interface {
	// contains filtered or unexported methods
}

Operation is a supported typed build operation. Use value forms of Run, Copy, Env and Workdir; pointer forms are not accepted.

type OperationProgress

type OperationProgress = api.OperationProgress

OperationProgress is a backend-independent observation of execution work.

type Options

type Options struct {
	// Progress receives bounded observations while supervised workers execute.
	// Callbacks run synchronously and must return; callers sharing a callback
	// across concurrent Execute calls synchronize it.
	Progress func(OperationProgress)
	// Network selects the default RUN network; it does not restrict registry traffic.
	Network string
	// Contexts supplies named local COPY and RUN inputs independently of ContextDir.
	Contexts                       map[string]string
	Store                          StoreOptions
	ContextDir, Runtime, Isolation string
	Jobs                           int
	Output                         Output
	Cache                          CacheOptions
	Registry                       RegistryOptions
	Stdout, Stderr                 io.Writer
}

Options supplies execution resources. ContextDir, when supplied, is an absolute directory. Jobs zero uses the backend default. Writers receive worker output; callers sharing writers across concurrent calls must synchronize them.

type Output

type Output struct {
	OCI, Filesystem string
	Exports         []api.FileExport
}

Output selects fresh absolute destinations whose parent directories exist. OCI optionally exports an image layout. With OCI empty, the native image is retained without image serialization. Filesystem exports the flattened root filesystem. Exports selects files or directories, including diagnostics after an ordinary failed RUN in the selected state. Outputs require confirmed cleanup and are promoted separately; existing paths are never overwritten.

type Program

type Program struct {
	Platform string
	States   []State
	Output   StateID
}

Program is an ordered, topological graph with one explicit final output. Platform defaults to the host platform. Independent states may run concurrently. Values are literal; coopr does not expand Coopr ARG or ENV expressions.

type RegistryOptions

type RegistryOptions struct {
	AuthFile, CertDir, Credentials, PullPolicy, SignaturePolicyPath string
	TLSVerify                                                       *bool
}

RegistryOptions controls native image authentication and pull policy.

type Result

type Result struct {
	ImageID, ManifestDigest, Platform, OCI, Filesystem string
	Cache                                              CacheStats
	ProgressDropped                                    uint64
	Exports                                            []api.ExportResult
}

Result identifies the completed image and caller-owned outputs.

func Execute

func Execute(ctx context.Context, program Program, options Options) (result Result, retErr error)

Execute validates and executes a static program using the same supervised graph scheduler, cache, process groups and cleanup path as Coopr's frontend.

type Run

type Run struct {
	Args   []string
	Mounts []Mount
}

Run executes Args directly, without adding a shell. Use an explicit shell argv when shell interpretation is desired.

type Source

type Source struct {
	Context string
	Image   string
	State   StateID
}

Source selects an image, earlier state or named local COPY context. Image "scratch" selects an empty filesystem. Inherited ONBUILD triggers are cleared without execution; frontend instruction expansion is outside this API. An empty Copy or bind-mount source uses ContextDir. Context selects a declared local named input for COPY or RUN mounts; it cannot supply a state base.

type State

type State struct {
	ID         StateID
	From       Source
	Operations []Operation
}

State derives a filesystem/image state from exactly one image or earlier state.

type StateID

type StateID string

StateID identifies a state within one program.

type StoreOptions

type StoreOptions struct {
	RunRoot, GraphRoot, Driver string
	DriverOptions              []string
}

StoreOptions selects caller-owned containers/storage roots. Both roots must be absolute and distinct. Driver defaults to native containers/storage policy.

type Workdir

type Workdir struct{ Path string }

Workdir selects a literal working directory.

Directories

Path Synopsis
Package api defines Coopr's versioned, transport-safe execution contract.
Package api defines Coopr's versioned, transport-safe execution contract.
Package client provides Coopr's versioned Unix-socket execution client.
Package client provides Coopr's versioned Unix-socket execution client.
cmd
coopr command
coopr-run-sequence command
coopr-run-sequence runs direct argv commands within one container execution.
coopr-run-sequence runs direct argv commands within one container execution.
coopr-sequoia-signing command
coopr-sequoia-signing is an optional native signing backend, never a container runtime dependency.
coopr-sequoia-signing is an optional native signing backend, never a container runtime dependency.
internal
apibackend
Package apibackend adapts public API requests to Coopr's existing backends.
Package apibackend adapts public API requests to Coopr's existing backends.
apiservice
Package apiservice serves Coopr's same-account execution API on Unix sockets.
Package apiservice serves Coopr's same-account execution API on Unix sockets.
build
Package build runs local Coopr definitions through the embedded Buildah backend.
Package build runs local Coopr definitions through the embedded Buildah backend.
buildah
Package buildah executes Coopr build operations directly through Buildah's library API.
Package buildah executes Coopr build operations directly through Buildah's library API.
buildcontext
Package buildcontext defines named inputs supplied independently of the primary build context.
Package buildcontext defines named inputs supplied independently of the primary build context.
cache
Package cache stores portable logical transformation results as OCI artifacts.
Package cache stores portable logical transformation results as OCI artifacts.
componentstore
Package componentstore manages Coopr's local OCI image-layout component store.
Package componentstore manages Coopr's local OCI image-layout component store.
definition
Package definition parses the ordered stage blocks in a Coopr definition.
Package definition parses the ordered stage blocks in a Coopr definition.
enginecopy
Package enginecopy delivers Coopr image indexes to Docker Engine.
Package enginecopy delivers Coopr image indexes to Docker Engine.
imageconfig
Package imageconfig owns Coopr's executor-neutral OCI image configuration.
Package imageconfig owns Coopr's executor-neutral OCI image configuration.
imagestore
Package imagestore operates on images in borrowed containers-storage handles.
Package imagestore operates on images in borrowed containers-storage handles.
localstore
Package localstore manages OCI graphs in Coopr-owned local image layouts.
Package localstore manages OCI graphs in Coopr-owned local image layouts.
oci
Package oci resolves OCI image and component references to verified content.
Package oci resolves OCI image and component references to verified content.
onbuildparse
Package onbuildparse converts Docker-format ONBUILD trigger strings into Coopr's executor-neutral instruction model.
Package onbuildparse converts Docker-format ONBUILD trigger strings into Coopr's executor-neutral instruction model.
planner
Package planner separates component publication from invocation without executing commands, resolving registries, or reading build-context files.
Package planner separates component publication from invocation without executing commands, resolving registries, or reading build-context files.
stateidentity
Package stateidentity hashes the logical contents of an effective rootfs and its image configuration.
Package stateidentity hashes the logical contents of an effective rootfs and its image configuration.
storeactivity
Package storeactivity coordinates long-lived Coopr store operations with destructive maintenance across processes.
Package storeactivity coordinates long-lived Coopr store operations with destructive maintenance across processes.
testutil/nativeimage
Package nativeimage seeds private native-store test fixtures.
Package nativeimage seeds private native-store test fixtures.
transfer
Package transfer copies already-built Coopr artifacts to named destinations.
Package transfer copies already-built Coopr artifacts to named destinations.
scripts

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL