Harbor

ContainerExitedError(strategy, logs)

Thrown when a container exits before satisfying its wait strategy — waiting longer cannot succeed, so the wait aborts immediately instead of running out the full wait_timeout. Carries the container's logs for diagnosis.

DockerError(cmd, exitcode, stderr)

Exception thrown when a docker CLI invocation exits with a non-zero status. Carries the failed command, its exit code, and any captured stderr output.

WaitTimeoutError(strategy, timeout, logs)

Thrown when a container fails to satisfy its wait strategy within wait_timeout seconds. Carries the container's logs at the time the wait gave up to make failures diagnosable.

cleanup!(container::Container; throw_errors::Bool=false)

Synchronously force-remove the container (stopping it if necessary). Safe to call multiple times; does nothing if the container was already removed via remove! or a previous cleanup!. A failed removal leaves the handle eligible for another cleanup attempt. Errors are logged as warnings by default; set throw_errors=true to propagate them. Otherwise, a warning identifies the container that may still exist.

docker_exec(container_id::String, exec_cmd::AbstractVector{<:AbstractString};
            detach::Bool=false, detach_keys::Union{Nothing,AbstractString}=nothing,
            env::Union{Nothing,AbstractDict{<:AbstractString,<:AbstractString}}=nothing,
            env_file::Union{Nothing,AbstractString,AbstractVector{<:AbstractString}}=nothing,
            interactive::Bool=false, privileged::Bool=false, tty::Bool=false,
            user::Union{Nothing,AbstractString}=nothing,
            workdir::Union{Nothing,AbstractString}=nothing) -> String

Runs docker exec on the specified container. Returns the command's stdout as a string. Throws a DockerError (carrying the exit code and captured stderr) if the command exits with a non-zero status.

docker_images() -> Vector{Image}

Runs docker images and returns a vector of Image structs. Dangling images (<none> repository or tag) are omitted.

docker_inspect_container(container_id::String) -> JSON object

Runs docker inspect <container_id> and returns the parsed JSON.

docker_kill(container_id::String; signal::Union{String,Int}="SIGKILL") -> Bool

Runs docker kill --signal=<signal> <container_id>. Returns true if successful.

docker_logs(container_id::String; follow::Bool=false, tail::Union{String,Int}="all") -> String

Runs docker logs with optional follow and tail parameters, returning the log output. The container's stdout and stderr streams are merged in the returned string.

docker_ps(; all::Bool=false, label=nothing) -> Vector{String}

Runs docker ps (or docker ps -a if all is true) and returns a vector of container IDs, optionally filtered to containers carrying the given label (a "key" or "key=value" string).

docker_pull(image_name::String; tag::String="latest", digest=nothing) -> Image

Runs docker pull <image_name>:<tag> (or <image_name>@<digest> when a digest is given). On success, returns an Image struct with the image's registry digest populated when it can be determined.

docker_resolved_ports(container_id::String) -> Dict{Int, Int}

Queries the actual container port => host port mappings of a (running) container via docker inspect, including ephemeral host ports assigned by the OS.

docker_restart(container_id::String; timeout::Int=10) -> Bool

Runs docker restart -t <timeout> <container_id>. Returns true if successful.

docker_rm(container_id::String; force::Bool=false) -> Bool

Runs docker rm [--force] <container_id>. Returns true if the container is removed.

docker_rm_image(image::Image; force::Bool=false) -> Bool

Runs docker rmi [--force] <image>. Returns true on success.

docker_run(image::Image; name=nothing, ports=Dict{Int,Int}(),
           volumes=Dict{String,String}(), environment=Dict{String,String}(),
           command=nothing, detach::Bool=false,
           labels=Dict{String,String}()) -> String

Runs docker run with the provided options and returns the container ID. ports maps container ports to host ports (a host port of 0 requests an OS-assigned ephemeral port); labels attaches --label key=value pairs.

docker_start(container_id::String) -> Bool

Runs docker start <container_id>. Returns true if successful.

docker_stop(container_id::String; timeout::Int=10) -> Bool

Runs docker stop -t <timeout> <container_id>. Returns true if successful.

exec(container::Container, exec_cmd::AbstractVector{<:AbstractString}; kw...) -> String

Runs a command inside the specified container and returns its stdout. Throws a DockerError carrying the exit code and captured stderr if the command fails. Supported keywords mirror docker exec flags: env, workdir, user, detach, interactive, tty, privileged, env_file, detach_keys. env values are passed through a mode-0600 temporary --env-file that is deleted after the docker CLI reads it. They are not placed on the command line or in the docker CLI's own environment. Names and values cannot contain NUL, CR, or LF.

host_port(container::Container, container_port::Integer) -> Int

Returns the host port that container_port is published on. This is the canonical way to reach a container whose ports were requested with an ephemeral host port (ports=Dict(container_port => 0)). Throws an ArgumentError if the container port is not published.

images() -> Vector{Image}

Retrieves a list of available images.

inspect(container::Container) -> Dict

Returns the container's full docker inspect output as a parsed JSON object.

is_running(container::Container) -> Bool

Queries docker for the container's live state. Returns false if the container no longer exists.

kill!(container::Container; signal="SIGKILL") -> Container

Sends signal to the container's main process (default SIGKILL). Returns the Container with an updated status.

logs(container::Container; follow::Bool=false, tail="all") -> String

Retrieves the logs (stdout and stderr merged) for the specified container. With follow=true the call blocks until the container stops, then returns the complete log output. tail limits the result to the last N lines.

prune() -> Int

Force-removes all containers on the host that were started by Harbor (identified by the org.juliaservices.harbor label), including ones leaked by crashed or killed Julia processes. Returns the number of containers removed. Containers not started by Harbor are never touched.

ps(; all::Bool=true) -> Vector{Container}

Lists containers. If all is true, lists all containers; otherwise, only running ones.

pull(image::String; tag::Union{Nothing, String}=nothing) -> Image

Pulls an image from a registry and returns an Image instance. image may be a bare name ("alpine"), include a tag ("alpine:3.19"), or be pinned to a digest ("alpine@sha256:..."). When no tag is given in either the reference or the tag keyword, "latest" is used. The returned Image records the image's registry digest when it can be determined.

remove!(container::Container; force::Bool=false) -> Bool

Removes a container from the system. Returns true if successful.

remove(image::Image; force::Bool=false) -> Bool

Removes the specified image.

For a digest-pinned Image with no tag, Docker removes the underlying image and every local tag that points to it. This is Docker's rmi name@digest behavior; use digest removal only when deleting all such tags is intended.

restart!(container::Container; timeout::Int=10) -> Container

Restarts a container (stopping it first if running, with timeout seconds of grace). Returns the Container with an updated status and refreshed host port mappings.

run!(image::Union{Image, AbstractString}; name=nothing, ports=Dict{Int,Int}(), volumes=Dict{String,String}(), environment=Dict{String,String}(), command=nothing, detach::Bool=true, waitstrategy=nothing, waittimeout=60.0, wait_interval=1.0) -> Container

Starts a container from the provided Image — or an image reference string, which is resolved against local images first and pulled only when absent — and returns a Container handle.

• ports maps container ports to host ports; a host port of 0 publishes the container port on an OS-assigned ephemeral port (see host_port). When ports is non-empty, no wait_strategy is given, and the run is detached, run! waits for the lowest mapped container port to be ready.
• wait_strategy may be (port=...,), (pattern=string_or_regex,), (url=..., expected_status=...), (healthy=true,), or a function container -> Bool. If the strategy is not satisfied within wait_timeout seconds (or the container exits before satisfying it), the container is removed and a WaitTimeoutError (or ContainerExitedError) is thrown.
• With detach=false the call blocks until the container exits and returns the handle even if the container's command exited with a non-zero status; use logs and inspect (State.ExitCode) to diagnose.
• environment values are passed through a mode-0600 temporary --env-file that is deleted after the docker CLI reads it. Values are not placed on the command line or in the docker CLI's own environment. Because Docker's env-file format is line-based, names and values cannot contain NUL, CR, or LF.

The started container is force-removed by a garbage-collection finalizer as a safety net; prefer with_container (or explicit remove!) for deterministic cleanup.

start!(container::Container) -> Container

Starts a stopped container. Returns the Container with an updated status and refreshed host port mappings (ephemeral ports may be re-assigned).

stop!(container::Container; timeout::Int=10) -> Container

Gracefully stops a running container. Returns the Container with a new status.

wait_for(container::Container)

Waits until the container's wait strategy condition is met or wait_timeout expires. Throws a WaitTimeoutError (including the container's logs) if the condition isn't satisfied in time, or a ContainerExitedError as soon as the container exits without having satisfied the strategy.

with_container(image::Image; kw...) do container # operations on container end

Runs a container with the specified image and keyword options. The container is force-removed synchronously after the block completes (even if an error occurs), so by the time with_container returns, the container is gone and its name and ports are free for reuse. If a graceful shutdown is required, call stop! on the container at the end of the block.

If container_logs_on_error=true, the container's logs are logged with @error before the block's exception is rethrown.

If cleanup fails after a successful block, the cleanup error is thrown. If the block already raised an exception, Harbor preserves that original exception and logs a cleanup warning instead. The handle remains eligible for a later cleanup! attempt.