exec_container (erlexec v2.6.0)

Container command helper for exec.

This module translates a container specification map into an argv form suitable for exec:run_link/3, choosing a container runtime and mapping high-level keys to runtime flags.

Runtime Selection

Default behavior (runtime => auto) prefers podman, then falls back to docker.
Explicit runtime names (podman, docker) are also supported.
A custom executable path can be provided via runtime as string or binary.

Runtime Cache

When called through exec_container:run_link/1, runtime executable paths are cached in persistent_term for faster subsequent calls.

The cache stores discovered paths for auto, podman, and/or docker.
Before use, cached paths are validated with filelib:is_file/1.
Missing stale paths are evicted and re-discovered.

Supported Spec Keys

image (required)
command (string/binary shell form or argv list)
args (argv list)
env (map or list of {Key, Value})
volumes ([{Host, Container}] or [{Host, Container, Mode :: text() | ro | rw | read_only | read_write}])
networks (list)
ports (list; mapped to -p / --publish)
memory_limit (mapped to --memory)
cpu_limit (mapped to --cpus, supports milli CPU strings like "500m")
runtime (auto | podman | docker | path)
remove (true by default, adds --rm)
timeout (mapped to exec option {timeout, Ms})
on_timeout (currently only kill)
exec_options (extra exec:run_link/2 options)
start_timeout (timeout used for exec:run_link/3 call)

Example

exec_container:run_link(#{
  image        => "alpine:3.20",
  command      => "echo hello",
  env          => #{"FOO" => "bar"},
  volumes      => [{"/tmp", "/work", "ro"}],
  ports        => [{"127.0.0.1", 8080, 80}, {udp, 5353, 5353}],
  cpu_limit    => "500m",
  memory_limit => "256M",
  timeout      => 5000
}).

Summary

Types

container_spec()

Specification map consumed by run_link/1.

env_kv()

Environment key/value pair used by the env field.

port_num()

Valid TCP/UDP port range.

port_spec()

Supported forms for one entry in the ports field.

proto()

Transport protocol qualifier used in port_spec() tuples.

text()

Text value accepted in container spec fields (string or binary).

volume_spec()

Volume mapping used by the volumes field.

Functions

run_link(Spec)

Run a container command using exec:run_link/3 through exec_container:run_link/1.

Types

container_spec()

-type container_spec() ::
          #{image := text(),
            command => text() | [text()],
            args => [text()],
            env => map() | [env_kv()],
            volumes => [volume_spec()],
            networks => [text()],
            ports => [port_spec()],
            memory_limit => text() | integer(),
            cpu_limit => text() | integer() | float(),
            runtime => auto | podman | docker | text(),
            remove => boolean(),
            timeout => non_neg_integer(),
            on_timeout => kill,
            exec_options => list(),
            start_timeout => pos_integer()}.

Specification map consumed by run_link/1.

Required key:

image

Optional keys:

command: string/binary shell command or argv list
args: extra argv list
env: map or list of {Key, Value} tuples
volumes: list of volume_spec() : mode supports standard values (for example "ro", "rw") and aliases read_only -> "ro", read_write -> "rw"
networks: list of network names
ports: list of port_spec()
memory_limit: value for --memory
cpu_limit: value for --cpus (milli values like "500m" are accepted)
runtime: auto (default), podman, docker, or explicit executable
remove: whether to add --rm (default true)
timeout: mapped to exec watchdog option {timeout, Ms}
on_timeout: currently only kill
exec_options: additional options passed through to exec:run_link/3
start_timeout: timeout for the exec:run_link/3 call itself

env_kv()

-type env_kv() :: {text(), text() | integer() | float()}.

Environment key/value pair used by the env field.

port_num()

-type port_num() :: 1..65535.

Valid TCP/UDP port range.

port_spec()

-type port_spec() ::
          port_num() |
          {HostPort :: port_num() | text(), ContainerPort :: port_num() | text()} |
          {HostIp :: text(), HostPort :: port_num() | text(), ContainerPort :: port_num() | text()} |
          {Proto :: proto(), HostPort :: port_num() | text(), ContainerPort :: port_num() | text()} |
          {HostIp :: text(),
           Proto :: proto(),
           HostPort :: port_num() | text(),
           ContainerPort :: port_num() | text()}.

Supported forms for one entry in the ports field.

proto()

-type proto() :: tcp | udp.

Transport protocol qualifier used in port_spec() tuples.

text()

-type text() :: string() | binary().

Text value accepted in container spec fields (string or binary).

volume_spec()

-type volume_spec() ::
          {HostPath :: text(), ContainerPath :: text()} |
          {HostPath :: text(),
           ContainerPath :: text(),
           Mode :: text() | ro | rw | read_only | read_write}.

Volume mapping used by the volumes field.

Functions

run_link(Spec)

-spec run_link(container_spec()) ->
                  {ok, pid(), integer()} | {ok, [{stdout | stderr, [binary()]}]} | {error, any()}.

Run a container command using exec:run_link/3 through exec_container:run_link/1.

The specification map is transformed into a runtime command line. On success, returns the same shape as exec:run_link/3.