DHE documentation update

Signed-off-by: Sven Dowideit <SvenDowideit@home.org.au>

docs/sources/docker-hub-enterprise/adminguide.md

@@ -53,7 +53,7 @@ following information:
 * Error logs
 * Crash logs
 
-## Emergency access to the DHE admin web interface
+## Emergency access to DHE
 
 If your authenticated or public access to the DHE web interface has stopped
 working, but your DHE admin container is still running, you can add an

docs/sources/docker-hub-enterprise/configuration.md

@@ -2,7 +2,9 @@ page_title: Docker Hub Enterprise: Configuration options
 page_description: Configuration instructions for Docker Hub Enterprise
 page_keywords: docker, documentation, about, technology, understanding, enterprise, hub, registry
 
-# Configuration options
+# Configuring DHE
+
+## Overview
 
 This page will help you properly configure Docker Hub Enterprise (DHE) so it can
 run in your environment. 
@@ -20,7 +22,7 @@ configuration options. You'll see options for configuring:
 
 ![Domain and Ports page</admin/settings#http>](../assets/admin-settings-http.png)
 
-* *Domain Name*: **required**; defaults to an empty string, the fully qualified domain name assigned to the DHE host.
+* *Domain Name*: **required** defaults to an empty string, the fully qualified domain name assigned to the DHE host.
 * *Load Balancer HTTP Port*: defaults to 80, used as the entry point for the image storage service. To see load balancer status, you can query
 http://&lt;dhe-host&gt;/load_balancer_status.
 * *Load Balancer HTTPS Port*: defaults to 443, used as the secure entry point
@@ -267,42 +269,85 @@ by the [Registry 2.0](http://docs.docker.com/registry/configuration/).
 
 ## Authentication
 
+The "Authentication" settings tab lets DHE administrators control access
+to the DHE web admin tool and to the DHE Registry.
+
 The current authentication methods are `None`, `Basic` and `LDAP`.
 
-The `Basic` setting includes:
+> **Note**: if you have issues logging into the DHE admin web interface after changing the authentication
+> settings, you may need to use the [emergency access to the DHE admin web interface](./adminguide.md#Emergency-access-to-the-dhe-admin-web-interface).
+
+### No authentication
+
+No authentication means that everyone that can access your DHE web administration
+site. This is not recommended for any use other than testing.
+
+
+### Basic authentication
+
+The `Basic` authentication setting allows the admin to provide username/password pairs local to DHE.
+Any user who can successfully authenticate can use DHE to push and pull Docker images.
+You can optionally filter the list of users to a subset of just those users with access to the DHE
+admin web interface.
 
 ![Basic authentication settings page</admin/settings#auth>](../assets/admin-settings-authentication-basic.png)
 
 * A button to add one user, or to upload a CSV file containing username,
 password pairs
 * A DHE website Administrator Filter, allowing you to either
-* * 'Allow all authenticated users' to log into the DHE admin web interface, or
-* * 'Whitelist usernames', which allows you to restrict access to the web
-interface to the listed set of users.
+* * *Allow all authenticated users*: to log into the DHE admin web interface, or
+* * *Whitelist usernames*: which allows you to restrict access to the web interface to a listed set of users.
 
-The `LDAP` setting includes:
+### LDAP authentication
+
+Using LDAP authentication allows you to integrate your DHE registry into your
+organization's existing user and authentication database.
+
+As this involves existing infrastructure external to DHE and Docker, you will need to
+gather the details required to configure DHE for your organization's particular LDAP
+implementation.
+
+You can test that you have the necessary LDAP server information by using it from
+inside a Docker container running on the same server as your DHE:
+
+> **Note**: if the LDAP server is configured to use *StartTLS*, then you need to add `-Z` to the
+> `ldapsearch` command examples below.
+
+```
+docker run --rm -it svendowideit/ldapsearch -h <LDAP Server hostname> -b <User Base DN> -D <Search User DN> -w <Search User Password>
+```
+
+or if the LDAP server is set up to allow anonymous access (which means your *Search User DN* and *Search User Password* settings can remain empty):
+
+```
+docker run --rm -it svendowideit/ldapsearch -h <LDAP Server hostname> -b <User Base DN> -x
+```
+
+The result of these queries should be a (very) long list - if you get an authentication error,
+then the details you have been given are not sufficient.
+
+The *User Login Attribute* key setting must match the field used in the LDAP server
+for the user's login-name. On OpenLDAP, it's generally `uid`, and on Microsoft Active Directory
+servers, it's `sAMAccountName`. The `ldapsearch` output above should allow you to
+confirm which setting you need.
 
 ![LDAP authentication settings page</admin/settings#auth>](../assets/admin-settings-authentication-ldap.png)
 
 * *Use StartTLS*: defaults to unchecked, check to enable StartTLS
-* *LDAP Server URL*: **required**; defaults to null, LDAP server URL (e.g., - ldap://example.com)
-* *User Base DN*: **required**; defaults to null, user base DN in the form
-(e.g., - dc=example,dc=com)
-* *User Login Attribute*: **required**; defaults to null, user login attribute
-(e.g., - uid or sAMAccountName)
-* *Search User DN*:** required**; defaults to null, search user DN
-(e.g., - domain\username)
-* *Search User Password*: **required**; defaults to null, search user password
-* A *DHE Registry User filter*, allowing you to either
-* * 'Allow all authenticated users' to push or pull any images, or
-* * 'Filter LDAP search results', which allows you to restrict DHE registry pull
-and push to users matching the LDAP filter,
-* * 'Whitelist usernames', which allows you to restrict DHE registry pull and
-push to the listed set of users.
+* *LDAP Server URL*: **required** defaults to null, LDAP server URL (e.g., - ldap://example.com)
+* *User Base DN*: **required** defaults to null, user base DN in the form (e.g., - dc=example,dc=com)
+* *User Login Attribute*: **required** defaults to null, user login attribute (e.g., - uid or sAMAccountName)
+* *Search User DN*: **required** defaults to null, search user DN (e.g., - domain\username)
+* *Search User Password*: **required** defaults to null, search user password
+* A *DHE Registry User filter*: allowing you to either
+* * *Allow all authenticated users* to push or pull any images, or
+* * *Filter LDAP search results*: which allows you to restrict DHE registry pull and push to users matching the LDAP filter,
+* * *Whitelist usernames*: which allows you to restrict DHE registry pull and push to the listed set of users.
 * A *DHE website Administrator filter*, allowing you to either
-* * 'Allow all authenticated users' to log into the DHE admin web interface, or
-* * 'Filter LDAP search results', which allows you to restrict DHE admin web access to users matching the LDAP filter,
-* * 'Whitelist usernames', which allows you to restrict access to the web interface to the listed set of users.
+* * *Allow all authenticated users*: to log into the DHE admin web interface, or
+* * *Filter LDAP search results*: which allows you to restrict DHE admin web access to users matching the LDAP filter,
+* * *Whitelist usernames*: which allows you to restrict access to the web interface to the listed set of users.
+
 
 ## Next Steps
 

docs/sources/docker-hub-enterprise/index.md

@@ -2,7 +2,9 @@ page_title: Docker Hub Enterprise: Overview
 page_description: Docker Hub Enterprise
 page_keywords: docker, documentation, about, technology, understanding, enterprise, hub, registry
 
-# Overview
+# Welcome to Docker Hub Enterprise
+
+## Overview
 
 Docker Hub Enterprise (DHE) lets you run and manage your own Docker image
 storage service, securely on your own infrastructure behind your company
@@ -29,7 +31,7 @@ DHE is perfect for:
 
 DHE is built on [version 2 of the Docker registry](https://github.com/docker/distribution).
 
-## Documentation
+## Available Documentation
 
 The following documentation for DHE is available:
 

docs/sources/docker-hub-enterprise/install.md

@@ -2,7 +2,7 @@ page_title: Docker Hub Enterprise: Install
 page_description: Installation instructions for Docker Hub Enterprise
 page_keywords: docker, documentation, about, technology, understanding, enterprise, hub, registry
 
-# Install
+# Installing Docker Hub Enterprise
 
 ## Overview
 
@@ -112,6 +112,7 @@ $ chmod 755 docker-cs-engine-deb.sh
 $ sudo ./docker-cs-engine-deb.sh
 $ sudo apt-get install docker-engine-cs
 ```
+Lastly, confirm Docker is running with `sudo service docker start`.
 
 In order to simplify using Docker, you can get non-sudo access to the Docker
 socket by adding your user to the `docker` group, then logging out and back in

docs/sources/docker-hub-enterprise/quick-start.md

@@ -46,7 +46,9 @@ You should be able to complete this guide in about thirty minutes.
 > fundamentals, please consult the
 > [Docker user guide](http://docs.docker.com/userguide/).
 
-First, you will retrieve a copy of the official Jenkins image from the Docker Hub. From the CLI of a machine running the Docker Engine on your network, use
+First, you will retrieve a copy of the official Jenkins image from the Docker Hub. By default, if
+Docker can't find an image locally, it will attempt to pull the image from the
+Docker Hub. From the CLI of a machine running the Docker Engine on your network, use
 the
 [`docker pull`](https://docs.docker.com/reference/commandline/cli/#pull)
 command to pull the public Jenkins image.
@@ -57,7 +59,7 @@ command to pull the public Jenkins image.
 > you are a member of the `docker` group, or have root privileges. Otherwise, you may
 > need to add `sudo` to the example commands below.
 
-Docker will start the process of pulling the image from the Hub. Once it has completed, the Jenkins image should be visible in the output of a [`docker images`](https://docs.docker.com/reference/commandline/cli/#images) command:
+Docker will start the process of pulling the image from the Hub. Once it has completed, the Jenkins image should be visible in the output of a [`docker images`](https://docs.docker.com/reference/commandline/cli/#images) command, which lists your available images:
 
     $ docker images
     REPOSITORY  TAG     IMAGE ID      CREATED      VIRTUAL SIZE
@@ -192,7 +194,27 @@ image pulled earlier:
 
 ## Pushing to Docker Hub Enterprise
 
-Now that you’ve create the custom image, it can be pushed to DHE using the
+> **Note**: If your DHE instance has authentication enabled, you will need to
+> use your command line to `docker login <dhe-hostname>` (e.g., `docker login
+> dhe.yourdomain.com`).
+>
+> Failures due to unauthenticated `docker push` and `docker pull` commands will
+> look like :
+>
+>     $ docker pull dhe.yourdomain.com/hello-world
+>     Pulling repository dhe.yourdomain.com/hello-world
+>     FATA[0001] Error: image hello-world:latest not found
+>
+>     $ docker push dhe.yourdomain.com/hello-world
+>     The push refers to a repository [dhe.yourdomain.com/hello-world] (len: 1)
+>     e45a5af57b00: Image push failed
+>     FATA[0001] Error pushing to registry: token auth attempt for registry
+>     https://dhe.yourdomain.com/v2/:
+>     https://dhe.yourdomain.com/auth/v2/token/
+>     ?scope=repository%3Ahello-world%3Apull%2Cpush&service=dhe.yourdomain.com
+>     request failed with status: 401 Unauthorized
+
+Now that you’ve created the custom image, it can be pushed to DHE using the
 [`docker push`command](https://docs.docker.com/reference/commandline/cli/#push):
 
     $ docker push dhe.yourdomain.com/ci-infrastructure/jnkns-img

docs/sources/docker-hub-enterprise/support.md

@@ -2,7 +2,9 @@ page_title: Docker Hub Enterprise: Support
 page_description: Commercial Support
 page_keywords: docker, documentation, about, technology, understanding, enterprise, hub, registry, support
 
-# Commercial Support
+# Commercial Support Options
+
+## How to get support
 
 Purchasing a DHE License or Commercial Support subscription means your questions
 and issues about DHE will receive prioritized support.

docs/sources/docker-hub-enterprise/userguide.md

@@ -10,10 +10,21 @@ need to know about, such as pushing or pulling images, etc. For tasks DHE
 administrators need to accomplish, such as configuring or monitoring DHE, please
 visit the [Administrator's Guide](./adminguide.md).
 
-## Using DHE to push and pull images
+## Overview
 
 The primary use case for DHE users is to push and pull images to and from the
-DHE image storage service. The following instructions describe these procedures.
+DHE image storage service. For example, you might pull an Official Image for
+Ubuntu from the Docker Hub, customize it with configuration settings for your
+infrastructure and then push it to your DHE image storage for other developers
+to pull and use for their development environments.
+
+Pushing and pulling images with DHE works very much like any other Docker
+registry: you use the `docker pull` command to retrieve images and the `docker
+push` command to add an image to a DHE repository. To learn more about Docker
+images, see
+[User Guide: Working with Docker Images](https://docs.docker.com/userguide/dockerimages/). For a step-by-step
+example of the entire process, see the
+[Quick Start: Basic Workflow Guide](./quick-start.md).
 
 > **Note**: If your DHE instance has authentication enabled, you will need to
 >use your command line to `docker login <dhe-hostname>` (e.g., `docker login
@@ -29,97 +40,81 @@ DHE image storage service. The following instructions describe these procedures.
 >     $ docker push dhe.yourdomain.com/hello-world
 >     The push refers to a repository [dhe.yourdomain.com/hello-world] (len: 1)
 >     e45a5af57b00: Image push failed
->     FATA[0001] Error pushing to registry: token auth attempt for registry https://dhe.yourdomain.com/v2/: https://>     dhe.yourdomain.com/auth/v2/token/?scope=repository%3Ahello-world%3Apull%2Cpush&service=dhe.yourdomain.com >     request failed with status: 401 Unauthorized
+>     FATA[0001] Error pushing to registry: token auth attempt for registry
+>     https://dhe.yourdomain.com/v2/:
+>     https://dhe.yourdomain.com/auth/v2/token/?scope=
+>     repository%3Ahello-world%3Apull%2Cpush&service=dhe.yourdomain.com
+>     request failed with status: 401 Unauthorized
 
+## Pushing Images
 
-1. Pull the `hello-world` official image from the Docker Hub. By default, if
-Docker can't find an image locally, it will attempt to pull the image from the
-Docker Hub.
+You push an image up to a DHE repository by using the
+[`docker push` command](https://docs.docker.com/reference/commandline/cli/#push).
 
-    `$ docker pull hello-world`
+You can add a `tag` to your image so that you can more easily identify it
+amongst other variants and so that it refers to your DHE server.
 
-2. List your available images.
+    `$ docker tag hello-world:latest dhe.yourdomain.com/yourusername/hello-mine:latest`
 
-        $ docker images
-        REPOSITORY     TAG     IMAGE ID      CREATED       VIRTUAL SIZE
-        hello-world    latest  e45a5af57b00  3 months ago  910 B
+The command labels a `hello-world:latest` image using a new tag in the
+`[REGISTRYHOST/][USERNAME/]NAME[:TAG]` format.  The `REGISTRYHOST` in this
+case is your DHE server, `dhe.yourdomain.com`, and the `USERNAME` is
+`yourusername`. Lastly, the image tag is set to `hello-mine:latest`.
 
-    Your list should include the `hello-world` image from the earlier run.
-
-3. Re-tag the `hello-world` image so that it refers to your DHE server.
-
-    `$ docker tag hello-world:latest dhe.yourdomain.com/demouser/hello-mine:latest`
-
-    The command labels a `hello-world:latest` image using a new tag in the
-    `[REGISTRYHOST/][USERNAME/]NAME[:TAG]` format.  The `REGISTRYHOST` in this
-    case is the DHE server, `dhe.yourdomain.com`, and the `USERNAME` is
-    `demouser`.
-
-4. List your new image.
-
-        $ docker images
-        REPOSITORY                           TAG     IMAGE ID      CREATED       VIRTUAL SIZE
-        hello-world                          latest  e45a5af57b00  3 months ago  910 B
-        dhe.yourdomain.com/demouser/hello-mine  latest  e45a5af57b00  3 months ago  910 B
-
-    You should see your new image label in the listing, with the same `IMAGE ID`
-    as the Official image.
-
-5. Push this new image to your DHE server.
+Once an image is tagged, you can push it to DHE with:
 
     `$ docker push dhe.yourdomain.com/demouser/hello-mine:latest`
+    
+> **Note**: If the Docker daemon on which you are running `docker push` doesn't
+> have the right certificates set up, you will get an error similar to:
+>
+>     $ docker push dhe.yourdomain.com/demouser/hello-world
+>     FATA[0000] Error response from daemon: v1 ping attempt failed with error:
+>     Get https://dhe.yourdomain.com/v1/_ping: x509: certificate signed by
+>     unknown authority. If this private registry supports only HTTP or HTTPS
+>     with an unknown CA certificate, please add `--insecure-registry
+>     dhe.yourdomain.com` to the daemon's arguments. In the case of HTTPS, if
+>     you have access to the registry's CA certificate, no need for the flag;
+>     simply place the CA certificate at
+>     /etc/docker/certs.d/dhe.yourdomain.com/ca.crt
 
-6. Set up a test of DHE by removing all images from your local environment:
+## Pulling images
 
-    `$ docker rmi -f $(docker images -q -a)`
+You can retrieve an image with the
+[`docker pull` command](https://docs.docker.com/reference/commandline/cli/#run),
+or you can retrieve an image and run Docker to build the container with the
+[`docker run`command](https://docs.docker.com/reference/commandline/cli/#run).
 
-    This command is for illustrative purposes only: removing the image forces
-    any subsequent `run` to pull from a remote registry (such as DHE) rather
-    than from a local cache. If you run `docker images` after this you should
-    not see any instance of `hello-world` or `hello-mine` in your images list.
+To retrieve an image from DHE and then run Docker to build the container, add
+the needed info to `docker run`:
 
-        $ docker images
-        REPOSITORY      TAG      IMAGE ID      CREATED       VIRTUAL SIZE
-
-7. Try running `hello-mine`.
-
-        $ docker run hello-mine
-        Unable to find image 'hello-mine:latest' locally
-        Pulling repository hello-mine
-        FATA[0007] Error: image library/hello-mine:latest not found
-
-    The `run` command fails because your new image doesn't exist on the Docker Hub.
-
-8. Run `hello-mine` again, this time pointing it to pull from DHE:
-
-        $ docker run dhe.yourdomain.com/demouser/hello-mine
-        latest: Pulling from dhe.yourdomain.com/demouser/hello-mine
+        $ docker run dhe.yourdomain.com/yourusername/hello-mine
+        latest: Pulling from dhe.yourdomain.com/yourusername/hello-mine
         511136ea3c5a: Pull complete
         31cbccb51277: Pull complete
         e45a5af57b00: Already exists
         Digest: sha256:45f0de377f861694517a1440c74aa32eecc3295ea803261d62f950b1b757bed1
         Status: Downloaded newer image for dhe.yourdomain.com/demouser/hello-mine:latest
 
-    If you run `docker images` after this you'll see a `hello-mine` image.
+Note that if you don't specify a version, by default the `latest` version of an
+image will be pulled.
+
+If you run `docker images` after this you'll see a `hello-mine` image.
 
         $ docker images
         REPOSITORY                           TAG     IMAGE ID      CREATED       VIRTUAL SIZE
-        dhe.yourdomain.com/demouser/hello-mine  latest  e45a5af57b00  3 months ago  910 B
+        dhe.yourdomain.com/yourusername/hello-mine  latest  e45a5af57b00  3 months ago  910 B
 
-> **Note**: If the Docker daemon on which you are running `docker push` doesn't
-> have the right certificates set up, you will get an error similar to:
->
->     $ docker push dhe.yourdomain.com/demouser/hello-world
->     FATA[0000] Error response from daemon: v1 ping attempt failed with error: Get https://dhe.yourdomain.com/v1/_ping: x509: certificate signed by unknown authority. If this private registry supports only HTTP or HTTPS with an unknown CA certificate, please add `--insecure-registry dhe.yourdomain.com` to the daemon's arguments. In the case of HTTPS, if you have access to the registry's CA certificate, no need for the flag; simply place the CA certificate at /etc/docker/certs.d/dhe.yourdomain.com/ca.crt
+To pull an image without building the container, use `docker pull` and specify
+your DHE registry by adding it to the command:
+
+     $ docker pull dhe.yourdomain.com/yourusername/hello-mine
 
-9. You have now successfully created a custom image, `hello-mine`, tagged it,
-    and pushed it to the image storage provided by your DHE instance. You then
-    pulled that image back down from DHE and onto your machine, where you can
-    use it to create a container containing the "Hello World" application..
 
 ## Next Steps
 
-For information on administering DHE, take a look at the [Administrator's Guide](./adminguide.md).
+For information on administering DHE, take a look at the
+[Administrator's Guide](./adminguide.md).
 
 
 <!--TODO:
@@ -127,4 +122,5 @@ For information on administering DHE, take a look at the [Administrator's Guide]
 * mention that image aliases that are not in the same repository are not updated - either on push or pull
 * but that multiple tags in one repo are pushed if you don't specify the `:tag` (ie, `imagename` does not always mean `imagename:latest`)
 * show what happens for non-latest, and when there are more than one tag in a repo
-* explain the fully-qualified repo/image name -->
+* explain the fully-qualified repo/image name
+* explain how to remove an image from DHE -->