Container targets and configuration

The target types and configuration properties contributed by the @fabr-build/container plugin (plugin @fabr-build/container;), which builds, pulls, pushes and runs OCI container images. Core definitions (like sync) are in Core targets and configuration.

This page is generated from fabr list-all, so it never drifts from the code.

Global properties

Property	Default	Description
CONTAINER_ENGINE	@host:docker	The container engine that runs images and build commands: Docker, or podman (@host:podman), whose commands are the same.
OCI_TARGET	${TARGET/-*/-unknown-linux}	The platform images are looked up at and built for: a target triple whose OS is linux. Only its CPU chooses among an image’s platforms.

Targets

oci_repository

targetdef oci_repository {
  url               = REQUIRED STRING;
  default_namespace = STRING;
  login_url         = STRING;
}

A registry speaking the OCI distribution API. A name in it is an image’s name and a tag or digest, so @docker:node:22-bookworm-slim:etc/os-release is that file of the image the tag names for OCI_TARGET.

Property	Type	Required	Description
url	REQUIRED STRING	yes	The registry’s URL, as in https://ghcr.io.
default_namespace	STRING		The namespace an image named by one segment is in (library on Docker Hub).
login_url	STRING		The address a login to the registry is filed under, as given to docker login or podman login: by default the host of url.

container_image

Operations: build, run

targetdef container_image {
  base     = PACKAGES;
  files    = FILES;
  entry    = STRING;
  args     = STRING;
  workdir  = STRING;
  user     = STRING;
  env      = MAP;
  ports    = STRING;
  build    = STRING;
  metadata = MAP;
}

An OCI image: base’s layers, and one layer above them holding files, with its settings applied to the base’s config. fabr ls, cat and cp read the image’s filesystem.

Property	Type	Required	Description
base	PACKAGES		The image to build on: a reference (@docker:debian:12-slim) or another container_image. None: an image of only this target’s layer.
files	FILES		Files placed in the image under their own names, from /. They are resolved for the image’s platform and the base’s C library.
entry	STRING		The program the container runs: a path or command inside the image. Replaces the base’s entrypoint and command.
args	STRING		Arguments placed after entry, ahead of any given when the image is run.
workdir	STRING		The directory the container’s process starts in.
user	STRING		The user the container’s process runs as (name, uid, uid:gid).
env	MAP		Environment variables, set over the base’s.
ports	STRING		Ports the image exposes: 8080, or with its protocol, 53/udp.
build	STRING		A shell command run in base (/bin/sh -c), its changes a layer below files’s: apt-get install -y …. It runs again only when base, the command, env or the platform changes; what it downloads is not tracked.
metadata	MAP		Facts about the image, written as its labels over the base’s: OCI’s keys (description, licenses, source, url, title, documentation, vendor, authors) as org.opencontainers.image.<key>, any other as written.

container_program

Operations: run

targetdef container_program {
  image   = REQUIRED PACKAGES;
  args    = STRING;
  env     = MAP;
  ports   = STRING;
  network = STRING;
  hosts   = MAP;
}

Property	Type	Required	Description
image	REQUIRED PACKAGES	yes	The image the program runs: a container_image, or a reference (@docker:redis:7-alpine).
args	STRING		Arguments given the image’s entry, after its own args and before any its caller gives.
env	MAP		Environment variables, set over the image’s.
ports	STRING		Ports published on the host: 8080:80, 5353:53/udp. None: each port the image exposes, on the same port of the host.
network	STRING		The network the container joins: host, or a named network.
hosts	MAP		Names added to the container’s hosts file, each an address, or host-gateway for the host.

Provided targets

Ready-made targets declared by these libraries, usable by name in any project.

@docker

oci_repository @docker {
  url               = https://registry-1.docker.io;
  default_namespace = library;
  login_url         = https://index.docker.io/v1/;
}

Docker Hub.