Skip to content

Latest commit

 

History

History
518 lines (388 loc) · 14.6 KB

user_manual.md

File metadata and controls

518 lines (388 loc) · 14.6 KB

User Manual

This user manual is made to correspond to Docker's API docs (e.g. API 1.18).

Creating a docker-client

// Create a client based on DOCKER_HOST and DOCKER_CERT_PATH env vars
final DockerClient docker = DefaultDockerClient.fromEnv().build();

// or use the builder
final DockerClient docker = DefaultDockerClient.builder()
  // Set various options
  .build();

Both DefaultDockerClient.builder() and DefaultDockerClient.fromEnv() return a DefaultDockerClient.Builder. The builder can be used to configure and build clients with custom timeouts, connection pool sizes, and other parameters.

Unix socket support

Unix socket support is available on Linux since v2.5.0:

final DockerClient docker = new DefaultDockerClient("unix:///var/run/docker.sock");

HTTPS support

We can connect to HTTPS-secured Docker instances with client-server authentication. The semantics are similar to using the DOCKER_CERT_PATH environment variable:

final DockerClient docker = DefaultDockerClient.builder()
    .uri(URI.create("https://boot2docker:2376"))
    .dockerCertificates(new DockerCertificates(Paths.get("/Users/rohan/.docker/boot2docker-vm/")))
    .build();

Connection pooling

We use the Apache HTTP client under the covers, with a shared connection pool per instance of the Docker client. The default size of this pool is 100 connections, so each instance of the Docker client can only have 100 concurrent requests in flight.

If you plan on waiting on more than 100 containers at a time (DockerClient.waitContainer), or otherwise need a higher number of concurrent requests, you can modify the connection pool size:

final DockerClient docker = DefaultDockerClient.fromEnv()
    .connectionPoolSize(SOME_LARGE_NUMBER)
    .build()

Note that the connect timeout is also applied to acquiring a connection from the pool. If the pool is exhausted and it takes too long to acquire a new connection for a request, we throw a DockerTimeoutException instead of just waiting forever on a connection becoming available.

Containers

List containers

final List<Container> containers = docker.listContainers();

// List all containers. Only running containers are shown by default.
final List<Container> containers = docker.listContainers(ListContainersParam.allContainers());

Create a container

final ContainerCreation container = docker.createContainer(ContainerConfig.builder().build());

Inspect a container

final ContainerInfo info = docker.inspectContainer("containerID");

List processes running inside a container

Not implemented. PRs welcome.

Get container logs

final String logs;
try (LogStream stream = client.logs("containerID", LogsParam.stdout(), LogsParam.stderr())) {
  logs = stream.readFully();
}

Inspect changes on a container's filesystem

Not implemented. PRs welcome.

Export a container

ImmutableSet.Builder<String> files = ImmutableSet.builder();
try (TarArchiveInputStream tarStream = new TarArchiveInputStream(docker.exportContainer(id))) {
  TarArchiveEntry entry;
  while ((entry = tarStream.getNextTarEntry()) != null) {
    files.add(entry.getName());
  }
}

Get container stats based on resource usage

final ContainerStats stats = docker.stats("containerID");

Resize a container TTY

Not implemented. PRs welcome.

Start a container

docker.startContainer("containerID");

Restart a container

docker.restartContainer("containerID");
// or with a seconds to wait before restarting parameter
docker.restartContainer("containerID", 10);

Kill a container

docker.killContainer("containerID");

Rename a container

docker.renameContainer("oldContainerID", "newContainerID");

Pause a container

docker.pauseContainer("containerID");

Unpause a container

docker.unpauseContainer("containerID");

Attach to a container

final String logs;
try (LogStream stream = docker.attachContainer(volumeContainer,
      AttachParameter.LOGS, AttachParameter.STDOUT,
      AttachParameter.STDERR, AttachParameter.STREAM)) {
  logs = stream.readFully();
}

Attach to a container (websocket)

Not implemented. PRs welcome.

Wait a container

final ContainerExit exit = docker.waitContainer("containerID");

Remove a container

docker.removeContainer("containerID");

Copy files or folders from a container

ImmutableSet.Builder<String> files = ImmutableSet.builder();
try (TarArchiveInputStream tarStream =
    new TarArchiveInputStream(docker.copyContainer(id, "/bin"))) {
  TarArchiveEntry entry;
  while ((entry = tarStream.getNextTarEntry()) != null) {
    files.add(entry.getName());
  }
}

Images

List images

final List<Image> quxImages = docker.listImages(ListImagesParam.withLabel("foo", "qux"));

Build image from a Dockerfile

final AtomicReference<String> imageIdFromMessage = new AtomicReference<>();

final String returnedImageId = docker.build(
    Paths.get(dockerDirectory), "test", new ProgressHandler() {
      @Override
      public void progress(ProgressMessage message) throws DockerException {
        final String imageId = message.buildImageId();
        if (imageId != null) {
          imageIdFromMessage.set(imageId);
        }
      }
    });

Create an image

// By pulling
final AuthConfig authConfig = AuthConfig.builder().email(AUTH_EMAIL).username(AUTH_USERNAME)
  .password(AUTH_PASSWORD).build();
docker.pull("dxia2/scratch-private:latest", authConfig);

// or by loading from a source
final File imageFile = new File("/path/to/image/file");
final String image = "busybox-test" + System.nanoTime();
try (InputStream imagePayload = new BufferedInputStream(new FileInputStream(imageFile))) {
  docker.load(image, imagePayload);
}

Inspect an image

final ImageInfo info = docker.inspectImage("imageID")

Get the history of an image

Not implemented yet. PRs welcome.

Push an image on the registry

docker.push("imageID");

Tag an image into a repository

docker.pull("busybox:latest");

final String name = "testRepo/tagForce:sometag";
// Assign name to first image
docker.tag("busybox:latest", name);

// Force-re-assign tag to another image
docker.tag("busybox:buildroot-2014.02", name, true);

Remove an image

docker.removeImage("imageID");

Search images

final List<ImageSearchResult> searchResult = docker.searchImages("busybox");

Miscellaneous

Check auth configuration

final AuthConfig authConfig = AuthConfig.builder().email(AUTH_EMAIL).username(AUTH_USERNAME)
  .password(AUTH_PASSWORD).build();
final int statusCode = docker.auth(authConfig);
assertThat(statusCode, equalTo(200));

Display system-wide information

final Info info = docker.info();

Show the docker version information

final Version version = docker.version();

Ping the docker server

final String pingResponse = docker.ping();
assertThat(pingResponse, equalTo("OK"));

Create a new image from a container's changes

// Pull image
docker.pull("busybox:latest");

// Create container
final ContainerConfig config = ContainerConfig.builder()
    .image("busybox:latest")
    .build();
final String name = randomName();
final ContainerCreation creation = docker.createContainer(config, name);
final String id = creation.id();

final String tag = "foobar";
final ContainerCreation newContainer = docker.commitContainer(
    id, "mosheeshel/busybox", tag, config, "CommitedByTest-" + tag, "newContainer");

final ImageInfo imageInfo = docker.inspectImage(newContainer.id());
assertThat(imageInfo.author(), is("newContainer"));
assertThat(imageInfo.comment(), is("CommitedByTest-" + "foobar"));

Monitor Docker's events

docker.pull("busybox:latest");
final EventStream eventStream = docker.events();
final ContainerConfig config = ContainerConfig.builder()
    .image("busybox:latest")
    .build();
final ContainerCreation container = docker.createContainer(config, randomName());
docker.startContainer(container.id());

final Event createEvent = eventStream.next();
assertThat(createEvent.status(), equalTo("create"));
assertThat(createEvent.id(), equalTo(container.id()));
assertThat(createEvent.from(), startsWith("busybox:"));
assertThat(createEvent.time(), notNullValue());

final Event startEvent = eventStream.next();
assertThat(startEvent.status(), equalTo("start"));
assertThat(startEvent.id(), equalTo(container.id()));
assertThat(startEvent.from(), startsWith("busybox:"));
assertThat(startEvent.time(), notNullValue());

eventStream.close();

Get a tarball containing all images in a repository

final File imageFile = save(BUSYBOX);
assertTrue(imageFile.length() > 0);

final File tmpDir = new File(System.getProperty("java.io.tmpdir"));
assertTrue("Temp directory " + tmpDir.getAbsolutePath() + " does not exist", tmpDir.exists());
final File imageFile = new File(tmpDir, "busybox-" + System.nanoTime() + ".tar");

imageFile.createNewFile();
imageFile.deleteOnExit();
final byte[] buffer = new byte[2048];
int read;

try (OutputStream imageOutput = new BufferedOutputStream(new FileOutputStream(imageFile))) {
  try (InputStream imageInput = docker.save("busybox", authConfig)) {
    while ((read = imageInput.read(buffer)) > -1) {
      imageOutput.write(buffer, 0, read);
    }
  }
}

Get a tarball containing all images.

Not implemented yet. PRs welcome.

Load a tarball with a set of images and tags into docker

Not implemented yet. PRs welcome.

Exec Create

final String execId = docker.execCreate(containerId, new String[]{"sh", "-c", "exit 2"});

try (final LogStream stream = docker.execStart(execId)) {
  stream.readFully();
}

final ExecState state = docker.execInspect(execId);
assertThat(state.id(), is(execId));
assertThat(state.running(), is(false));
assertThat(state.exitCode(), is(2));
assertThat(state.openStdin(), is(true));
assertThat(state.openStderr(), is(true));
assertThat(state.openStdout(), is(true));
}

Exec Start

See example above.

Exec Resize

Not implemented yet. PRs welcome.

Exec Inspect

See example above.

Mounting volumes in a container

To mount a host directory into a container, create the container with a HostConfig. You can set the local path and remote path in the binds() method on the HostConfig.Builder. There are two ways to make a bind:

  1. Pass binds() a set of strings of the form "local_path:container_path".
  2. Create a Bind object and pass it to binds().

If you only need to create a volume in a container, and you don't need it to mount any particular directory on the host, you can use the volumes() method on the ContainerConfig.Builder.

final HostConfig hostConfig =
  HostConfig.builder()
    .appendBinds("/local/path:/remote/path")
    .appendBinds(Bind.from("/another/local/path")
               .to("/another/remote/path")
               .readOnly(true)
               .build())
    .build();
final ContainerConfig volumeConfig =
  ContainerConfig.builder()
    .image("busybox:latest")
    .volumes("/foo")   // This volume will not mount any host directory
    .hostConfig(hostConfig)
    .build();

A note on mounts

Be aware that, starting with API version 1.20 (docker version 1.8.x), information about a container's volumes is returned with the key "Mounts", not "Volumes". As such, the ContainerInfo.volumes() method is deprecated. Instead, use ContainerInfo.mounts().