2 Managing Docker Containers and Images

Racket

2 Managing Docker Containers and Images🔗ℹ

The remote-shell/docker library provides support for working with Docker images and containers. The library is a fairly thin wrapper on the docker command, which is located via find-executable-path.

Added in version 1.3 of package remote-shell-lib.

procedure
(docker-build #:name name
#:content content
[ #:platform platform
#:dockerfile dockerfile
#:build-args build-args
#:buildx? buildx?
#:cache-from cache-from
#:cache-to cache-to]) → void?
  name : string?
  content : path-string?
  platform : (or/c #f string?) = #f
  dockerfile : (or/c #f path-string?) = #f
   build-args :
(hash/c (or/c bytes-environment-variable-name?
              string-environment-variable-name?)
        (or/c string-no-nuls?
              bytes-no-nuls?))
= (hash)
  buildx? : (or/c #f 'load 'push) = #f
  cache-from : (listof string?) = '()
  cache-to : (listof string?) = '()

Builds a new Docker image tagged by name, using the content directory to create the image. The content directory should contain a file named "Dockerfile" unless dockerfile is supplied to override that path. The optional platform argument can select a platform different than the host default, when supported by the host Docker installation, such as using "linux/amd64" on AArch64 Mac OS.

If dockerfile is a path, it is passed as the --file argument to docker build, allowing the Dockerfile to live outside content.

The build-args argument supplies a mapping of --build-arg key/value pairs to make available as ARG substitutions inside the Dockerfile.

If buildx? is 'load, the build runs as docker buildx build --load so that the resulting image is loaded into the local Docker daemon. If buildx? is 'push, the build runs as docker buildx build --push so that the resulting image is pushed to a registry. Use cache-from and cache-to (each a list of strings passed verbatim to --cache-from and --cache-to) to participate in a build cache. Both lists require buildx? to be set.

Changed in version 1.7 of package remote-shell-lib: Added the #:platform argument.
Changed in version 1.10: Added the #:dockerfile, #:build-args, #:buildx?, #:cache-from, and #:cache-to arguments.

procedure
(docker-image-id #:name name) → (or/c #f string?)
name : string?

Returns the identity of a Docker image tagged by name, returning #f if no such image exists.

procedure
(docker-image-remove #:name name) → void?
name : string?

Removes the Docker image indicated by name (or, at least, removes the tagged reference, but the image may persist if it has other names).

procedure
(docker-create #:name name
#:image-name image-name
[ #:platform platform
#:network network
#:volumes volumes
#:envvars envvars
#:ports ports
#:memory-mb memory-mb
#:swap-mb swap-mb
#:replace? replace?]) → string?
  name : string?
  image-name : string?
  platform : (or/c #f string?) = #f
  network : (or/c #f string?) = #f
   volumes : (listof (list/c path-string? string? (or/c 'ro 'rw)))
= '()
   envvars :
(hash/c (or/c bytes-environment-variable-name?
              string-environment-variable-name?)
        (or/c string-no-nuls?
              bytes-no-nuls?))
= (hash)
   ports : (hash/c listen-port-number? listen-port-number?)
= (hash)
  memory-mb : (or/c #f exact-positive-integer?) = #f
  swap-mb : (or/c #f exact-positive-integer?) = #f
  replace? : boolean? = #f

Creates a Docker container as name as an instance of image-name. If replace? is true, then any existing container using the name is stopped (if running) and removed, first. The newly created container is not running.

If platform is a string, then the created container uses that platform. Specifying a platform is useful when a host can run multiple platforms and image-name is also available for multiple platforms.

If network is a string, then the created container uses that network.

The volumes argument supplies a mapping of host directories to container directory paths, where the path on the container maps to the host directory in the indicated mode: 'ro for read-only or 'rw for read–write.

The envvars argument supplies a mapping of environment variable names to values for the container’s environment.

The ports argument supplies a mapping of host port numbers to container port numbers, where attempts to connect to the host port number at the host will be forward to the container at the container’s port number. Using 0 as the host port allocates an ephemeral port for the host.

The memory-mb and swap-mb arguments determine the amount of memory that the container can use in megabytes (MB), where memory-mb is “real” memory and swap-mb is additional swap space. If only one of the numbers is provided, the default for the other is the same (i.e., by default, the total amount of memory available including swap space is twice the provided value). If neither is provided as a number, no specific limit is imposed on the container.

Changed in version 1.5 of package remote-shell-lib: Added #:memory-mb and #:swap-mb.
Changed in version 1.6: Added #:platform.
Changed in version 1.8: Added #:envvars and #:ports.

procedure
(docker-id #:name name) → (or/c #f string?)
name : string?

Returns the identity of a Docker container name, returning #f if no such container exists.

procedure
(docker-running? #:name name) → boolean?
name : string?

Determines whether the Docker container name (which must exist) is currently running.

procedure
(docker-remove #:name name) → void?
name : string?

Removes the Docker container name, which must exist and must not be running.

procedure
(docker-start #:name name) → void?
name : string?

Starts the Docker container name, which must exist and must not be running.

procedure
(docker-stop #:name name #:wait? wait?) → void?
name : string?
wait? : #t

Stops the Docker container name, which must exist and must be running.

If wait? is true, then docker-stop returns only after docker-running? returns #f, since a container may stay in the running state for some time after requesting a stop.

Changed in version 1.9 of package remote-shell-lib: Added #:wait?.

procedure
(docker-exec #:name name
command
arg ...
[ #:mode mode
#:user user
#:workdir workdir]) → (or/c boolean? void?)
  name : string?
  command : path-string?
  arg : path-string?
  mode : (or/c 'error 'result) = 'error
  user : (or/c #f string?) = #f
  workdir : (or/c #f path-string?) = #f

Executes command with args on the Docker container name, which must exist and be running.

The mode argument determines how failure of the command is handled—either because the command exits with failure on the container or due to a problem accessing the container—as well as the return value for success. The 'error mode raises an exception for failure and returns (void) for success, while 'result mode returns a boolean indicating whether the command was successful.

If user is a string, it is passed as the --user argument to docker container exec, so the command runs as the given user (or uid, or uid:gid) instead of the container’s default user. If workdir is a path, it is passed as --workdir, so the command runs with the given working directory inside the container instead of the image’s default.

Changed in version 1.10 of package remote-shell-lib: Added the #:user and #:workdir arguments.

procedure
(docker-copy #:name name
#:src src
#:dest dest
[ #:mode mode]) → (or/c boolean? void?)
  name : string?
  src : path-string?
  dest : path-string?
  mode : (or/c 'error 'result) = 'error

Copies a file to or from the Docker container name. One of src or dest should refer to a file on the host machine, and the other should be a string prefixed with the name and ":" to indicate a path on the container.

The mode argument determines how failure of the copy is handled—either due to path problems or a problem accessing the container—as well as the return value for success. The 'error mode raises an exception for failure and returns (void) for success, while 'result mode returns a boolean indicating whether the copy was successful.

1	Remote Shells
2	Managing Docker Containers and Images
3	Managing Virtual Box Machines