Merge pull request #781 from spotify/auth-documentation

document RegistryAuthSupplier in the user manual

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## 8.7.0 (not yet released)
+## 8.7.0 (released June 5, 2017)
 
 ### Expanded RegistryAuthSupplier support
 Add RegistryAuthSuppliers for:

README.md

@@ -47,15 +47,6 @@ final DockerClient docker = DefaultDockerClient.fromEnv().build();
 // Pull an image
 docker.pull("busybox");
 
-// Pull an image from a private repository
-// Server address defaults to "https://index.docker.io/v1/"
-RegistryAuth registryAuth = RegistryAuth.builder().email("foo@bar.com").username("foobar")
-  .password("secret-password").serverAddress("https://myprivateregistry.com/v1/").build();
-docker.pull("foobar/busybox-private:latest", registryAuth);
-
-// You can also set the RegistryAuth for the DockerClient instead of passing everytime you call pull()
-DockerClient docker = DefaultDockerClient.fromEnv().registryAuth(registryAuth).build();
-
 // Bind container ports to host ports
 final String[] ports = {"80", "22"};
 final Map<String, List<PortBinding>> portBindings = new HashMap<>();
@@ -111,7 +102,6 @@ docker.close();
 If you're looking for how to use docker-client, see the [User Manual][2].
 If you're looking for how to build and develop it, keep reading.
 
-
 ## Prerequisites
 
 docker-client should be buildable on any platform with Docker 1.6+, JDK7+, and a recent version of

docs/user_manual.md

@@ -6,6 +6,7 @@ This user manual is made to correspond to Docker's [API docs][1] (e.g. [API 1.18
   * [Unix socket support](#unix-socket-support)
   * [HTTPS support](#https-support)
   * [Connection pooling](#connection-pooling)
+* [Authentication to private registries](#authentication-to-private-registries)
 * [Containers](#containers)
   * [List containers](#list-containers)
   * [Create a container](#create-a-container)
@@ -114,6 +115,35 @@ Note that the connect timeout is also applied to acquiring a connection from the
 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.
 
+## Authentication to private registries
+
+Authentication info when building, pushing, or pulling images, or when using
+Swarm, is provided by a `RegistryAuthSupplier` class.
+
+Docker-client is packaged with a few implementations of this interface
+
+- `auth.ConfigFileRegistryAuthSupplier`, which reads authentication info from
+  the the config files used by docker-cli (`~/.dockercfg` or
+  `~/.docker/config.json`)
+- `auth.NoOpRegistryAuthSupplier` which uses a fixed instance of the
+  `RegistryAuth` and `RegistryConfigs` POJOs
+- `auth.gcr.ContainerRegistryAuthSupplier`, which programmatically fetches
+  access tokens for use with Google Container Registry based on given Gogole
+  Cloud account credentials
+- `auth.MultiRegistryAuthSupplier`, which can be used to combine multiple other
+  implementations
+
+Users are encouraged to implement the `RegistryAuthSupplier` interface
+themselves to support custom authentication logic, and we would be happy to
+review and accept pull requests to add support in the library for additional
+schemes.
+
+Since version 8.7.0, docker-client will automatically enable the
+`ConfigFileRegistryAuthSupplier` class in `DefaultDockerClient` as long as none
+of the other authentication-related methods in the
+`DefaultDockerClient.Builder` class (`dockerAuth(boolean)`,
+`registryAuth(RegistryAuth)`, or `registryAuthSupplier(RegistryAuthSupplier)`)
+are used.
 
 ## Containers