lbuildah

A wrapper for buildah(1) commands. Create OCI containers in Lua instead of Dockerfile, Containerfile instructions or shell scripts. With buildah you have built-in layer squashing, faster builds, daemon-less operation, and capability for regular(non-root) users to create containers among other things. This wrapper also has useful abstractions such as removing whole toolchains from the container’s filesystem like Alpine apk-tools and Debian apt/dpkg.

A DSL module for LadyLua.

Lint and formatting

You can use selene and stylua for linting and formatting your code. A selene configuration is bundled with buildah.lua.

Sample

Check the sample directory in the repo for a sample of a non-trivial Dockerfile converted to Lua.

DSL

Besides the documented commands below, this DSL module also has a string interpolation extension.

Example:

JENKINS_HOME = "/var/jenkins_home"
CONFIG.ENV = "JENKINS_HOME=%s" % JENKINS_HOME

Runtime requirements

• buildah

• coreutils

• rsync

• crun

ℹ️	All instructions will signal an exit on error.

ℹ️	Any instructions before FROM() is skipped.

Table of Contents

• FROM ([IMAGE][, ID][, ASSETS])
  • Arguments
• ADD (SOURCE, DESTINATION[, CHOWN][, CHMOD])
  • Arguments
• RUN (COMMAND)
  • Arguments
• SCRIPT (FILE)
  • Arguments
• SH (COMMAND)
  • Arguments
• APT_GET (COMMAND)
  • Arguments
• APT_PURGE (PACKAGE)
  • Arguments
• APK (COMMAND)
  • Arguments
• COPY (SOURCE, DESTINATION[, CHOWN][, CHMOD])
  • Arguments
• UPLOAD (SOURCE, DESTINATION)
  • Arguments
• DOWNLOAD (SOURCE[, DESTINATION])
  • Arguments
• MKDIR (DIRECTORY[, MODE])
  • Arguments
• CHMOD (PATH, MODE)
  • Arguments
• RM (PATH)
  • Arguments
  • Example
• NOTIFY (MAP)
  • Usage
  • Map
  • Example
• CONFIG (MAP)
  • Usage
  • Map
  • Example
• ENTRYPOINT (…​)
  • Arguments
• COMMIT (NAME)
  • Arguments
• PUSH (NAME, URL)
  • Arguments
• ARCHIVE (PATH)
  • Arguments
• DIR (PATH)
  • Arguments
• TAR (PATH)
  • Arguments
• PURGE (OPTION)
  • Arguments
  • Option

FROM ([IMAGE][, ID][, ASSETS])

Creates a new working container, either from scratch, an image, or using an existing container as a starting point.

Arguments

Required	Type	Description	Default	Example
No	string	Container image	scratch	docker://docker.io/library/debian:buster-slim
No	string	A 27-character KSUID. If set, reuses the previously created container with specified ID	Generated KSUID	1kk…​
No	string	Assets directory	current directory "."	/home/ed/buildah

ADD (SOURCE, DESTINATION[, CHOWN][, CHMOD])

Adds the contents of a file, URL, or directory to a destination path within the container.

Arguments

Required	Type	Description	Default	Example
Yes	string	File or URL		sysctl.conf
Yes	string	Path		/etc/sysctl.conf
No	string	chown string, user and group ownership of destination		ed:ed
No	string	chmod string, access permissions of destination		0644

RUN (COMMAND)

Runs a specified command and arguments using the container’s root filesystem as a root filesystem.

Arguments

Required	Type	Description	Default	Example
Yes	string	Command and arguments as one long string		apk add vim

SCRIPT (FILE)

Runs a shell script upon the container’s root filesystem. Does NOT run the script within the container.

Arguments

Required	Type	Description	Default	Example
Yes	string	Shell script, without a leading (/) it reads from the ASSETS directory set in FROM()		find_suid.sh

SH (COMMAND)

Runs a shell command under the container’s root filesystem. Require’s a /bin/sh inside the container.

Arguments

Required	Type	Description	Default	Example
Yes	string	Command as one long string		echo "something"

APT_GET (COMMAND)

Run Debian apt-get command and arguments.

Arguments

Required	Type	Description	Default	Example
Yes	string	apt-get commands as one long string		install tmux

APT_PURGE (PACKAGE)

Run Debian dpkg --purge on specified package.

Arguments

Required	Type	Description	Default	Example
Yes	string	Debian package name		tmux

APK (COMMAND)

Run APK command inside an Alpine Linux container.

Arguments

Required	Type	Description	Default	Example
Yes	string	APK command as one long string		add tmux

COPY (SOURCE, DESTINATION[, CHOWN][, CHMOD])

Copy file to a destination path within the container.

Arguments

Required	Type	Description	Default	Example
Yes	string	File, without a leading (/) it attempts to copy from the ASSETS directory set in FROM()		sysctl.conf
No	string	Path	Copies SOURCE to the container’s root(/) directory	/etc/sysctl.conf
No	string	chown string, user and group ownership of destination		ed:ed
No	string	chmod string, access permissions of destination		0644

UPLOAD (SOURCE, DESTINATION)

Copy file to a destination path within the container. Difference with COPY is that this can read .dockerignore.

Arguments

Required	Type	Description	Default	Example
Yes	string	File, without a leading (/) it attempts to copy from the ASSETS directory set in FROM()		sysctl.conf
Yes	string	Path		/etc/sysctl.conf

DOWNLOAD (SOURCE[, DESTINATION])

Copy file from container to destination path.

Arguments

Required	Type	Description	Default	Example
Yes	string	Path within container		/sysctl.conf
No	string	Path	.

MKDIR (DIRECTORY[, MODE])

Creates directories and parent directories as needed within the container.

Arguments

Required	Type	Description	Default	Example
Yes	string	Directory		/home/ed/bin
No	string	Directory mode as in chmod(1)		0700

CHMOD (PATH, MODE)

Runs chmod(1) against the specified path.

Arguments

Required	Type	Description	Default	Example
Yes	string	Path		/home/ed/bin
Yes	string	Mode		0700

RM (PATH)

Deletes specified path(string) or paths(list).

Arguments

Required	Type	Description	Default	Example
Yes	string or table(list)	Path or paths		See below

Example

RM("/etc/sysctl.conf")
paths = {
  "/etc/sysctl.conf",
  "/etc/hosts",
}
RM(paths)

NOTIFY (MAP)

Send start and end instruction notification.

Usage

Required	Type	Description
Yes	map	Key(string)-Value(string)

Map

Key	Description	Example
TELEGRAM	Send to Telegram channel, requires a TELEGRAM_TOKEN environment variable	string: "-123123123"
PUSHOVER	Send to Pushover registered device, requires a PUSHOVER_TOKEN environment variable	string: "a09mfg9349vmv"
SLACK	Send message to Slack webhook, requires a SLACK_WEBHOOK environment variable	string: "T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"

Example

NOTIFY.TELEGRAM = "-30390312"

CONFIG (MAP)

Apply configuration settings to container.

Usage

Required	Type	Description
Yes	map	Key(string)-Value(string)

Map

Key	Description	Example
ANNOTATION	Annotation
ARCH	Architecture
AUTHOR	Author
CMD	Default command
COMMENT	Comment
DOMAINNAME	Domain name
ENV	environment variable
healthcheck	Health check command
healthcheck-interval	Health check command interval
healthcheck-retries	Health check command number of retries
healthcheck-start-period	Amount of time to wait after starting a container before a failed health check counts as a failure
healthcheck-timeout	Maximum time to wait for health check command
HOSTNAME	Host name
LABEL	Labels
OS	Operating system
PORT	Ports to expose
SHELL	Shell
STOP-SIGNAL	Signal e.g. SIGTERM
USER	Default user
VOLUME	Volume	/home/e
WORKINGDIR	Default working directory

Example

CONFIG.ENV = "PATH=/usr/bin"

ENTRYPOINT (…​)

Apply --entrypoint and --stop-signal in one instruction.

stop-signal is SIGTERM.

Arguments

Required	Type	Description	Default	Example
Yes	varargs	Sequence of executable arguments		"/sbin/tini", "--", "/usr/local/bin/jenkins.sh"

COMMIT (NAME)

Writes the container into local containers-storage. Finalizes and deletes the container being worked on.

Arguments

Required	Type	Description	Default	Example
Yes	string	Name and tag		alpine:new

PUSH (NAME, URL)

Push container image from containers-storage to URL, usually a container repository. Credentials are taken from environment variables BUILDAH_USER and BUILDAH_PASS.

Arguments

Required	Type	Description	Default	Example
Yes	string	Name		alpine:edge
Yes	string	URL		docker://example.com/alpine:edge

ARCHIVE (PATH)

Create an OCI archive of the container. Finalizes and deletes the container being worked on.

Arguments

Required	Type	Description	Default	Example
Yes	string	Destination path for archive

DIR (PATH)

Writes contents of OCI image into directory. Finalizes and deletes the container being worked on.

Arguments

Required	Type	Description	Default	Example
Yes	string	Destination path

TAR (PATH)

Writes contents of container root directory to a TAR file.

Arguments

Required	Type	Description	Default	Example
Yes	string	Destination path

PURGE (OPTION)

Purges a set of files and directories from the container.

Arguments

Required	Type	Description	Default	Example
Yes	string	See below

Option

String	Description
deb	apt and dpkg toolchain from Debian-based images
perl	Perl
apk	apk toolchain from Alpine Linux images
userland	common Linux userland