2 Managing Docker Containers and Images

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]) → void?
  name : string?
  content : path-string?
  platform : (or/c string?) = #f

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". 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.

Changed in version 1.7 of package remote-shell-lib: Added the #:platform argument.

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) → void?
name : string?

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

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

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.

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