On this page:
docker-build
docker-image-id
docker-image-remove
docker-create
docker-id
docker-running?
docker-remove
docker-start
docker-stop
docker-exec
docker-copy

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)  void?
  name : string?
  content : path-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".

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    
  #: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)))
   = '()
  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 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.

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.