herolib_rust/src/docs/rhai/buildah.md

Buildah Module

The Buildah module provides functions for working with containers and images using the Buildah tool. Buildah helps you create and manage container images.

Image Information

Image Properties

When working with images, you can access the following information:

• id: The unique identifier for the image
• names: A list of names/tags for the image
• name: The primary name of the image, or <none> if the image has no names
• size: The size of the image
• created: When the image was created

Container Functions

bah_from(image)

Creates a container from an image.

Parameters:

• image (string): The name or ID of the image to create the container from

Returns: The ID of the newly created container if successful.

Example:

// Create a container from an image
let result = bah_from("alpine:latest");
let container_id = result.stdout;
print(`Created container: ${container_id}`);

bah_run(container, command)

Runs a command in a container.

Parameters:

• container (string): The container ID or name
• command (string): The command to run

Returns: The output of the command if successful.

Example:

// Run a command in a container
let result = bah_run("my-container", "echo 'Hello from container'");
print(result.stdout);

bah_run_with_isolation(container, command, isolation)

Runs a command in a container with specified isolation.

Parameters:

• container (string): The container ID or name
• command (string): The command to run
• isolation (string): The isolation type (e.g., "chroot", "rootless", "oci")

Returns: The output of the command if successful.

Example:

// Run a command with specific isolation
let result = bah_run_with_isolation("my-container", "ls -la", "chroot");
print(result.stdout);

bah_copy(container, source, dest)

Copies files into a container.

Parameters:

• container (string): The container ID or name
• source (string): The source path on the host
• dest (string): The destination path in the container

Returns: A success message if the copy operation worked.

Example:

// Copy a file into a container
bah_copy("my-container", "./app.js", "/app/app.js");

bah_add(container, source, dest)

Adds files into a container. Similar to bah_copy but can also handle remote URLs.

Parameters:

• container (string): The container ID or name
• source (string): The source path on the host or a URL
• dest (string): The destination path in the container

Returns: A success message if the add operation worked.

Example:

// Add a file from a URL into a container
bah_add("my-container", "https://example.com/file.tar.gz", "/app/");

bah_commit(container, image_name)

Commits a container to an image.

Parameters:

• container (string): The container ID or name
• image_name (string): The name to give the new image

Returns: A success message if the commit operation worked.

Example:

// Commit a container to an image
bah_commit("my-container", "my-image:latest");

bah_remove(container)

Removes a container.

Parameters:

• container (string): The container ID or name

Returns: A success message if the container was removed.

Example:

// Remove a container
bah_remove("my-container");

bah_list()

Lists containers.

Returns: A list of containers if successful.

Example:

// List containers
let result = bah_list();
print(result.stdout);

bah_new_build_options()

Creates a new map with default build options.

Returns: A map with the following default options:

• tag (unit/null): The tag for the image (default: null)
• context_dir (string): The build context directory (default: ".")
• file (string): The Dockerfile path (default: "Dockerfile")
• isolation (unit/null): The isolation type (default: null)

Example:

// Create build options
let options = bah_new_build_options();

bah_build(options)

Builds an image with options specified in a map.

Parameters:

• options (map): A map of options created with bah_new_build_options()

Returns: A success message if the build operation worked.

Example:

// Create and customize build options
let options = bah_new_build_options();
options.tag = "my-image:latest";
options.context_dir = "./app";
options.file = "Dockerfile.prod";
options.isolation = "chroot";

// Build an image with options
let result = bah_build(options);

Image Functions

bah_images()

Lists images in local storage.

Returns: A list of images if successful.

Example:

// List images
let images = bah_images();

// Display image information
for image in images {
    print(`ID: ${image.id}, Name: ${image.name}, Size: ${image.size}, Created: ${image.created}`);
}

bah_image_remove(image)

Removes one or more images.

Parameters:

• image (string): The image ID or name

Returns: A success message if the image was removed.

Example:

// Remove an image
bah_image_remove("my-image:latest");

bah_image_push(image, destination, tls_verify)

Pushes an image to a registry.

Parameters:

• image (string): The image ID or name
• destination (string): The destination registry/repository
• tls_verify (boolean): Whether to verify TLS certificates

Returns: A success message if the image was pushed.

Example:

// Push an image to a registry
bah_image_push("my-image:latest", "registry.example.com/my-repo/my-image:latest", true);

bah_image_tag(image, new_name)

Adds an additional name to a local image.

Parameters:

• image (string): The image ID or name
• new_name (string): The new name to add

Returns: A success message if the image was tagged.

Example:

// Tag an image with a new name
bah_image_tag("my-image:latest", "my-image:v1.0");

bah_image_pull(image, tls_verify)

Pulls an image from a registry.

Parameters:

• image (string): The image to pull
• tls_verify (boolean): Whether to verify TLS certificates

Returns: A success message if the image was pulled.

Example:

// Pull an image from a registry
bah_image_pull("alpine:latest", true);

bah_new_commit_options()

Creates a new map with default commit options.

Returns: A map with the following default options:

• format (unit/null): The format of the image (default: null)
• squash (boolean): Whether to squash layers (default: false)
• rm (boolean): Whether to remove the container after commit (default: false)

Example:

// Create commit options
let options = bah_new_commit_options();

bah_image_commit(container, image_name, options)

Commits a container to an image with options specified in a map.

Parameters:

• container (string): The container ID or name
• image_name (string): The name to give the new image
• options (map): A map of options created with bah_new_commit_options()

Returns: A success message if the image was created.

Example:

// Create and customize commit options
let options = bah_new_commit_options();
options.format = "docker";
options.squash = true;
options.rm = true;

// Commit a container to an image with options
let result = bah_image_commit("my-container", "my-image:latest", options);

bah_new_config_options()

Creates a new map for config options.

Returns: An empty map to be filled with configuration options.

Example:

// Create config options
let options = bah_new_config_options();

bah_config(container, options)

Configures a container with options specified in a map.

Parameters:

• container (string): The container ID or name
• options (map): A map of options created with bah_new_config_options()

Returns: A success message if the container was configured.

Example:

// Create and customize config options
let options = bah_new_config_options();
options.author = "John Doe";
options.cmd = "echo Hello";
options.entrypoint = "/bin/sh -c";
options.workingdir = "/app";
options.env = "NODE_ENV=production";
options.label = "version=1.0";

// Configure a container with options
let result = bah_config("my-container", options);