Merge pull request #12729 from SvenDowideit/dhe-documentation-master-pr

Dhe documentation master pr

docs/mkdocs.yml

@@ -78,10 +78,14 @@ pages:
 - ['docker-hub/builds.md', 'Docker Hub', 'Automated Builds']
 - ['docker-hub/official_repos.md', 'Docker Hub', 'Official repo guidelines']
 
-# Docker Hub Enterprise
+# Docker Hub Enterprise:
-#- ['docker-hub-enterprise/index.md', '**HIDDEN**' ]
+- ['docker-hub-enterprise/index.md', 'Docker Hub Enterprise', 'Overview' ]
-#- ['docker-hub-enterprise/install-config.md', 'Docker Hub Enterprise', 'Installation and Configuration' ]
+- ['docker-hub-enterprise/quick-start.md', 'Docker Hub Enterprise', 'Quick Start: Basic Workflow' ]
-#- ['docker-hub-enterprise/usage.md', 'Docker Hub Enterprise', 'User Guide' ]
+- ['docker-hub-enterprise/userguide.md', 'Docker Hub Enterprise', 'User Guide' ]
+- ['docker-hub-enterprise/adminguide.md', 'Docker Hub Enterprise', 'Admin Guide' ]
+- ['docker-hub-enterprise/install.md', 'Docker Hub Enterprise', '  Installation' ]
+- ['docker-hub-enterprise/configuration.md', 'Docker Hub Enterprise', '  Configuration options' ]
+- ['docker-hub-enterprise/support.md', 'Docker Hub Enterprise', 'Support' ]
 
 # Examples:
 - ['examples/index.md', '**HIDDEN**']
@@ -195,17 +199,17 @@ pages:
 
 # Project:
 - ['project/index.md', '**HIDDEN**']
-- ['project/who-written-for.md', 'Contributor Guide', 'README first']
+- ['project/who-written-for.md', 'Contribute', 'README first']
-- ['project/software-required.md', 'Contributor Guide', 'Get required software'] 
+- ['project/software-required.md', 'Contribute', 'Get required software']
-- ['project/set-up-git.md', 'Contributor Guide', 'Configure Git for contributing'] 
+- ['project/set-up-git.md', 'Contribute', 'Configure Git for contributing']
-- ['project/set-up-dev-env.md', 'Contributor Guide', 'Work with a development container'] 
+- ['project/set-up-dev-env.md', 'Contribute', 'Work with a development container']
-- ['project/test-and-docs.md', 'Contributor Guide', 'Run tests and test documentation']
+- ['project/test-and-docs.md', 'Contribute', 'Run tests and test documentation']
-- ['project/make-a-contribution.md', 'Contributor Guide', 'Understand contribution workflow']
+- ['project/make-a-contribution.md', 'Contribute', 'Understand contribution workflow']
-- ['project/find-an-issue.md', 'Contributor Guide', 'Find an issue'] 
+- ['project/find-an-issue.md', 'Contribute', 'Find an issue']
-- ['project/work-issue.md', 'Contributor Guide', 'Work on an issue'] 
+- ['project/work-issue.md', 'Contribute', 'Work on an issue']
-- ['project/create-pr.md', 'Contributor Guide', 'Create a pull request'] 
+- ['project/create-pr.md', 'Contribute', 'Create a pull request']
-- ['project/review-pr.md', 'Contributor Guide', 'Participate in the PR review'] 
+- ['project/review-pr.md', 'Contribute', 'Participate in the PR review']
-- ['project/advanced-contributing.md', 'Contributor Guide', 'Advanced contributing']
+- ['project/advanced-contributing.md', 'Contribute', 'Advanced contributing']
-- ['project/get-help.md', 'Contributor Guide', 'Where to get help']
+- ['project/get-help.md', 'Contribute', 'Where to get help']
-- ['project/coding-style.md', 'Contributor Guide', 'Coding style guide']
+- ['project/coding-style.md', 'Contribute', 'Coding style guide']
-- ['project/doc-style.md', 'Contributor Guide', 'Documentation style guide']
+- ['project/doc-style.md', 'Contribute', 'Documentation style guide']

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

@@ -0,0 +1,103 @@
+page_title: Docker Hub Enterprise: Admin guide
+page_description: Documentation describing administration of Docker Hub Enterprise
+page_keywords: docker, documentation, about, technology, hub, enterprise
+
+# Docker Hub Enterprise Administrator's Guide
+
+This guide covers tasks and functions an administrator of Docker Hub Enterprise
+(DHE) will need to know about, such as reporting, logging, system management,
+performance metrics, etc.
+For tasks DHE users need to accomplish, such as using DHE to push and pull
+images, please visit the [User's Guide](./userguide).
+
+## Reporting
+
+### System Health
+
+![System Health page</admin/metrics/>](../assets/admin-metrics.png)
+
+The "System Health" tab displays resource utilization metrics for the DHE host
+as well as for each of its contained services. The CPU and RAM usage meters at
+the top indicate overall resource usage for the host, while detailed time-series
+charts are provided below for each service. You can mouse-over the charts or
+meters to see detailed data points.
+
+Clicking on a service name (i.e., "load_balancer", "admin_server", etc.) will
+display the network, CPU, and memory (RAM) utilization data for the specified
+service. See below for a
+[detailed explanation of the available services](#services).
+
+### Logs
+
+![System Logs page</admin/logs/>](../assets/admin-logs.png)
+
+Click the "Logs" tab to view all logs related to your DHE instance. You will see
+log sections on this page for each service in your DHE instance. Older or newer
+logs can be loaded by scrolling up or down. See below for a
+[detailed explanation of the available services](#services).
+
+DHE's log files can be found on the host in `/usr/local/etc/dhe/logs/`. The
+files are limited to a maximum size of 64mb. They are rotated every two weeks,
+when the aggregator sends logs to the collection server, or they are rotated if
+a logfile would exceed 64mb without rotation. Log files are named `<component
+name>-<timestamp at rotation>`, where the "component name" is the service it
+provides (`manager`, `admin-server`, etc.).
+
+### Usage statistics and crash reports
+
+During normal use, DHE generates usage statistics and crash reports. This
+information is collected by Docker, Inc. to help us prioritize features, fix
+bugs, and improve our products. Specifically, Docker, Inc. collects the
+following information:
+
+* Error logs
+* Crash logs
+
+## Emergency access to the DHE admin web interface
+
+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
+[ambassador container](https://docs.docker.com/articles/ambassador_pattern_linking/)
+to get temporary unsecure access to it by running:
+
+    $ docker run --rm -it --link docker_hub_enterprise_admin_server:admin -p 9999:80 svendowideit/ambassador
+
+> **Note:** This guide assumes you can run Docker commands from a machine where
+> you are a member of the `docker` group, or have root privileges. Otherwise,
+> you may need to add `sudo` to the example command above.
+
+This will give you access on port `9999` on your DHE server - `http://<dhe-host-ip>:9999/admin/`.
+
+## Services
+
+DHE runs several Docker services which are essential to its reliability and
+usability. The following services are included; you can see their details by
+running queries on the [System Health](#system-health) and [Logs](#logs) pages:
+
+* `admin_server`: Used for displaying system health, performing upgrades,
+configuring settings, and viewing logs.
+* `load_balancer`: Used for maintaining high availability by distributing load
+to each image storage service (`image_storage_X`).
+* `log_aggregator`: A microservice used for aggregating logs from each of the
+other services. Handles log persistence and rotation on disk.
+* `image_storage_X`: Stores Docker images using the [Docker Registry HTTP API V2](https://github.com/docker/distribution/blob/master/doc/SPEC.md). Typically,
+multiple image storage services are used in order to provide greater uptime and
+faster, more efficient resource utilization.
+
+## DHE system management
+
+The `dockerhubenterprise/manager` image is used to control the DHE system. This
+image uses the Docker socket to orchestrate the multiple services that comprise
+DHE.
+
+     $ sudo bash -c "$(sudo docker run dockerhubenterprise/manager [COMMAND])"
+
+Supported commands are: `install`, `start`, `stop`, `restart`, `status`, and
+`upgrade`.
+
+> **Note**: `sudo` is needed for `dockerhubenterprise/manager` commands to
+> ensure that the Bash script is run with full access to the Docker host.
+
+## Next Steps
+
+For information on installing DHE, take a look at the [Installation instructions](./install.md).

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

@@ -0,0 +1,311 @@
+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
+
+This page will help you properly configure Docker Hub Enterprise (DHE) so it can
+run in your environment. 
+
+Start with DHE loaded in your browser and click  the "Settings" tab to view
+configuration options. You'll see options for configuring:
+
+* Domains and ports
+* Security settings
+* Storage settings
+* Authentication settings
+* Your DHE license
+
+## Domains and Ports
+
+![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.
+* *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
+for the image storage service.
+* *HTTP_PROXY*: defaults to an empty string, proxy server for HTTP requests.
+* *HTTPS_PROXY*: defaults to an empty string, proxy server for HTTPS requests.
+* *NO_PROXY*: defaults to an empty string, proxy bypass for HTTP and HTTPS requests.
+
+
+> **Note**: If you need DHE to re-generate a self-signed certificate at some
+> point, you'll need to first delete `/usr/local/etc/dhe/ssl/server.pem`, and
+> then restart the DHE containers, either by changing and saving the "Domain Name",
+> or using `bash -c "$(docker run dockerhubenterprise/manager restart)"`.
+
+
+## Security
+
+![Security settings page</admin/settings#security>](../assets/admin-settings-security.png)
+
+* *SSL Certificate*: Used to enter the hash (string) from the SSL Certificate.
+This cert must be accompanied by its private key, entered below.
+* *Private Key*: The hash from the private key associated with the provided
+SSL Certificate (as a standard x509 key pair).
+
+In order to run, DHE requires encrypted communications via HTTPS/SSL between (a) the DHE registry and your Docker Engine(s), and (b) between your web browser and the DHE admin server. There are a few options for setting this up:
+
+1. You can use the self-signed certificate DHE generates by default.
+2. You can generate your own certificates using a public service or your enterprise's infrastructure. See the [Generating SSL certificates](#generating-ssl-certificates) section for the options available.
+
+If you are generating your own certificates, you can install them by following the instructions for
+[Adding your own registry certificates to DHE](#adding-your-own-registry-certificates-to-dhe).
+
+On the other hand, if you choose to use the DHE-generated certificates, or the
+certificates you generate yourself are not trusted by your client Docker hosts,
+you will need to do one of the following:
+
+* [Install a registry certificate on all of your client Docker daemons](#installing-registry-certificates-on-client-docker-daemons),
+
+* Set your [client Docker daemons to run with an unconfirmed connection to the registry](#if-you-cant-install-the-certificates).
+
+### Generating SSL certificates
+
+There are three basic approaches to generating certificates:
+
+1.  Most enterprises will have private key infrastructure (PKI) in place to
+generate keys. Consult with your security team or whomever manages your private
+key infrastructure. If you have this resource available, Docker recommends you
+use it.
+
+2. If your enterprise can't provide keys, you can use a public Certificate
+Authority (CA) like "InstantSSL.com" or "RapidSSL.com" to generate a
+certificate. If your certificates are generated using a globally trusted
+Certificate Authority, you won't need to install them on all of your
+client Docker daemons.
+
+3. Use the self-signed registry certificate generated by DHE, and install it
+onto the client Docker daemon hosts as shown below.
+
+### Adding your own Registry certificates to DHE
+
+Whichever method you use to generate certificates, once you have them
+you can set up your DHE server to use them by navigating to the "Settings" page,
+going to "Security," and putting the SSL Certificate text (including all
+intermediate Certificates, starting with the host) into the
+"SSL Certificate" edit box, and the previously generated Private key into
+the "SSL Private Key" edit box.
+
+Click the "Save" button, and then wait for the DHE Admin site to restart and
+reload. It should now be using the new certificate.
+
+Once the "Security" page has reloaded, it will show `#` hashes instead of the
+certificate text you pasted in.
+
+If your certificate is signed by a chain of Certificate Authorities that are
+already trusted by your Docker daemon servers, you can skip the "Installing
+registry certificates" step below.
+
+### Installing Registry certificates on client Docker daemons
+
+If your certificates do not have a trusted Certificate Authority, you will need
+to install them on each client Docker daemon host.
+
+The procedure for installing the DHE certificates on each Linux distribution has
+slightly different steps, as shown below.
+
+You can test this certificate using `curl`:
+
+```
+$ curl https://dhe.yourdomain.com/v2/
+curl: (60) SSL certificate problem: self signed certificate
+More details here: http://curl.haxx.se/docs/sslcerts.html
+
+curl performs SSL certificate verification by default, using a "bundle"
+ of Certificate Authority (CA) public keys (CA certs). If the default
+ bundle file isn't adequate, you can specify an alternate file
+ using the --cacert option.
+If this HTTPS server uses a certificate signed by a CA represented in
+ the bundle, the certificate verification probably failed due to a
+ problem with the certificate (it might be expired, or the name might
+ not match the domain name in the URL).
+If you'd like to turn off curl's verification of the certificate, use
+ the -k (or --insecure) option.
+
+$ curl --cacert /usr/local/etc/dhe/ssl/server.pem https://dhe.yourdomain.com/v2/
+{"errors":[{"code":"UNAUTHORIZED","message":"access to the requested resource is not authorized","detail":null}]}
+```
+
+Continue by following the steps corresponding to your chosen OS.
+
+#### Ubuntu/Debian
+
+```
+    $ export DOMAIN_NAME=dhe.yourdomain.com
+    $ openssl s_client -connect $DOMAIN_NAME:443 -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM | tee /usr/local/share/ca-certificates/$DOMAIN_NAME.crt
+    $ update-ca-certificates
+    Updating certificates in /etc/ssl/certs... 1 added, 0 removed; done.
+    Running hooks in /etc/ca-certificates/update.d....done.
+    $ service docker restart
+    docker stop/waiting
+    docker start/running, process 29291
+```
+
+#### RHEL
+
+```
+    $ export DOMAIN_NAME=dhe.yourdomain.com
+    $ openssl s_client -connect $DOMAIN_NAME:443 -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM | tee /etc/pki/ca-trust/source/anchors/$DOMAIN_NAME.crt
+    $ update-ca-trust
+    $ /bin/systemctl restart docker.service
+```
+
+#### Boot2Docker 1.6.0
+
+Install the CA cert (or the auto-generated cert) by adding the following to
+your `/var/lib/boot2docker/bootsync.sh`:
+
+```
+#!/bin/sh
+
+cat /var/lib/boot2docker/server.pem >> /etc/ssl/certs/ca-certificates.crt
+```
+
+
+Then get the certificate from the new DHE server using:
+
+```
+$ openssl s_client -connect dhe.yourdomain.com:443 -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM | sudo tee -a /var/lib/boot2docker/server.pem
+```
+
+If your certificate chain is complicated, you may want to use the changes in
+[Pull request 807](https://github.com/boot2docker/boot2docker/pull/807/files)
+
+Now you can either reboot your Boot2Docker virtual machine, or run the following to
+install the server certificate, and then restart the Docker daemon.
+
+```
+$ sudo chmod 755 /var/lib/boot2docker/bootsync.sh
+$ sudo /var/lib/boot2docker/bootsync.sh
+$ sudo /etc/init.d/docker restart`.
+```
+
+### If you can't install the certificates
+
+If for some reason you can't install the certificate chain on a client Docker host,
+or your certificates do not have a global CA, you can configure your Docker daemon to run in "insecure" mode. This is done by adding an extra flag,
+`--insecure-registry host-ip|domain-name`, to your client Docker daemon startup flags.
+You'll need to restart the Docker daemon for the change to take effect.
+
+This flag means that the communications between your Docker client and the DHE
+Registry server are still encrypted, but the client Docker daemon is not
+confirming that the Registry connection is not being hijacked or diverted.
+
+> **Note**: If you enter a "Domain Name" into the "Security" settings, it needs
+> to be DNS resolvable on any client Docker daemons that are running in
+> "insecure-registry" mode.
+
+To set the flag, follow the directions below for your operating system.
+
+#### Ubuntu
+
+On Ubuntu 14.04 LTS, you customize the Docker daemon configuration with the
+`/etc/defaults/docker` file.
+
+Open or create the `/etc/defaults/docker` file, and add the
+`--insecure-registry` flag to the `DOCKER_OPTS` setting (which may need to be
+added or uncommented) as follows:
+
+```
+DOCKER_OPTS="--insecure-registry dhe.yourdomain.com"
+```
+
+Then restart the Docker daemon with `sudo service docker restart`.
+
+#### RHEL
+
+On RHEL, you customize the Docker daemon configuration with the
+`/etc/sysconfig/docker` file.
+
+Open or create the `/etc/sysconfig/docker` file, and add the
+`--insecure-registry` flag to the `OPTIONS` setting (which may need to be
+added or uncommented) as follows:
+
+```
+OPTIONS="--insecure-registry dhe.yourdomain.com"
+```
+
+Then restart the Docker daemon with `sudo service docker restart`.
+
+### Boot2Docker
+
+On Boot2Docker, you customize the Docker daemon configuration with the
+`/var/lib/boot2docker/profile` file.
+
+Open or create the `/var/lib/boot2docker/profile` file, and add an `EXTRA_ARGS`
+setting as follows:
+
+```
+EXTRA_ARGS="--insecure-registry dhe.yourdomain.com"
+```
+
+Then restart the Docker daemon with `sudo /etc/init.d/docker restart`.
+
+## Image Storage Configuration
+
+DHE offers multiple methods for image storage, which are defined using specific
+storage drivers. Image storage can be local, remote, or on a cloud service such
+as S3. Storage drivers can be added or customized via the DHE storage driver
+API.
+
+![Storage settings page</admin/settings#storage>](../assets/admin-settings-storage.png)
+
+* *Yaml configuration file*: This file (`/usr/local/etc/dhe/storage.yml`) is
+used to configure the image storage services. The editable text of the file is
+displayed in the dialog box. The schema of this file is identical to that used
+by the [Registry 2.0](http://docs.docker.com/registry/configuration/).
+* If you are using the file system driver to provide local image storage, you will need to specify a root directory which will get mounted as a sub-path of
+`/var/local/dhe/image-storage`. The default value of this root directory is
+`/local`, so the full path to it is `/var/local/dhe/image-storage/local`.
+
+> **Note:**
+> Saving changes you've made to settings will restart the Docker Hub Enterprise
+> instance. The restart may cause a brief interruption for users of the image
+> storage system.
+
+## Authentication
+
+The current authentication methods are `None`, `Basic` and `LDAP`.
+
+The `Basic` setting includes:
+
+![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.
+
+The `LDAP` setting includes:
+
+![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.
+* 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.
+
+## Next Steps
+
+For information on getting support for DHE, take a look at the
+[Support information](./support.md).
+

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

@@ -0,0 +1,50 @@
+page_title: Docker Hub Enterprise: Overview
+page_description: Docker Hub Enterprise
+page_keywords: docker, documentation, about, technology, understanding, enterprise, hub, registry
+
+# Overview
+
+Docker Hub Enterprise (DHE) lets you run and manage your own Docker image
+storage service, securely on your own infrastructure behind your company
+firewall. This allows you to securely store, push, and pull the images used by
+your enterprise to build, ship, and run applications. DHE also provides
+monitoring and usage information to help you understand the workloads being
+placed on it.
+
+Specifically, DHE provides:
+
+* An image registry to store, manage, and collaborate on Docker images
+* Pluggable storage drivers
+* Configuration options to let you run DHE in your particular enterprise
+environment.
+* Easy, transparent upgrades
+* Logging, usage and system health metrics
+
+DHE is perfect for:
+
+* Providing a secure, on-premise development environment
+* Creating a streamlined build pipeline
+* Building a consistent, high-performance test/QA environment
+* Managing image deployment
+
+DHE is built on [version 2 of the Docker registry](https://github.com/docker/distribution).
+
+## Documentation
+
+The following documentation for DHE is available:
+
+* **Overview** This page.
+* [**Quick Start: Basic User Workflow**](./quick-start.md) Go here to learn the
+fundamentals of how DHE works and how you can set up a simple, but useful
+workflow.
+* [**User Guide**](./userguide.md) Go here to learn about using DHE from day to
+day.
+* [**Administrator Guide**](./adminguide.md) Go here if you are an administrator
+responsible for running and maintaining DHE.
+* [**Installation**](install.md) Go here for the steps you'll need to install
+DHE and get it working.
+* [**Configuration**](./configuration.md) Go here to find out details about
+setting up and configuring DHE for your particular environment.
+* [**Support**](./support.md) Go here for information on getting support for
+DHE.
+

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

@@ -1,8 +0,0 @@
-page_title: Using Docker Hub Enterprise installation
-page_description: Docker Hub Enterprise installation
-page_keywords: docker hub enterprise
-
-# Docker Hub Enterprise installation
-
-Documenation coming soon.
-

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

@@ -0,0 +1,312 @@
+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
+
+## Overview
+
+This document describes the process of obtaining, installing, and securing
+Docker Hub Enterprise (DHE). DHE is installed from Docker containers. Once
+installed, you will need to select a method of securing it. This doc will
+explain the options you have for security and help you find the resources needed
+to configure it according to your chosen method. More configuration details can
+be found in the [DHE Configuration page](./configuration.md).
+
+Specifically, installation requires completion of these steps, in order:
+
+1. Acquire a license by purchasing DHE or requesting a trial license.
+2. Install the commercially supported Docker Engine.
+3. Install DHE
+4. Add your license to your DHE instance
+
+## Licensing
+
+In order to run DHE, you will need to acquire a license, either by purchasing
+DHE or requesting a trial license. The license will be associated with your
+Docker Hub account or Docker Hub organization (so if you don't have an account,
+you'll need to set one up, which can be done at the same time as your license
+request). To get your license or start your trial, please contact our
+[sales department](mailto:sales@docker.com). Upon completion of your purchase or
+request, you will receive an email with further instructions for licensing your
+copy of DHE.
+
+## Prerequisites
+
+DHE requires the following:
+
+* Commercially supported Docker Engine 1.6.0 or later running on an
+Ubuntu 14.04 LTS, RHEL 7.1 or RHEL 7.0 host. (See below for instructions on how
+to install the commercially supported Docker Engine.)
+
+> **Note:** In order to remain in compliance with your DHE support agreement,
+> you must use the current version of commercially supported Docker Engine.
+> Running the regular, open source version of Engine is **not** supported.
+
+* Your Docker daemon needs to be listening to the Unix socket (the default) so
+that it can be bind-mounted into the DHE management containers, allowing
+DHE to manage itself and its updates. For this reason, your DHE host will also
+need internet connectivity so it can access the updates.
+
+* Your host also needs to have TCP ports `80` and `443` available for the DHE
+container port mapping.
+
+* You will also need the Docker Hub user-name and password used when obtaining
+the DHE license (or the user-name of an administrator of the Hub organization
+that obtained an Enterprise license).
+
+## Installing the Commercially Supported Docker Engine
+
+Since DHE is installed using Docker, the commercially supported Docker Engine
+must be installed first. This is done with an RPM or DEB repository, which you
+set up using a Bash script downloaded from the [Docker Hub](https://hub.docker.com).
+
+### Download the commercially supported Docker Engine installation script
+
+To download the commercially supported Docker Engine Bash installation script,
+log in to the [Docker Hub](https://hub.docker.com) with the user-name used to
+obtain your license . Once you're logged in, go to the
+["Enterprise Licenses"](https://registry.hub.docker.com/account/licenses/) page
+in your Hub account's "Settings" section.
+
+Select your intended host operating system from the "Download CS Engine" drop-
+down at the top right of the page and then, once the Bash setup script is
+downloaded, follow the steps below appropriate for your chosen OS.
+
+![Docker Hub Docker engine install dropdown](../assets/docker-hub-org-enterprise-license-CSDE-dropdown.png)
+
+### RHEL 7.0/7.1 installation
+
+First, copy the downloaded Bash setup script to your RHEL host. Next, run the
+following to install commercially supported Docker Engine and its dependencies,
+and then start the Docker daemon:
+
+```
+$ sudo yum update && sudo yum upgrade
+$ chmod 755 docker-cs-engine-rpm.sh
+$ sudo ./docker-cs-engine-rpm.sh
+$ sudo yum install docker-engine-cs
+$ sudo systemctl enable docker.service
+$ sudo systemctl start docker.service
+```
+
+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
+again:
+
+```
+$ sudo usermod -a -G docker $USER
+$ exit
+```
+
+> **Note**: you may need to reboot your server to update its RHEL kernel.
+
+### Ubuntu 14.04 LTS installation
+
+First, copy the downloaded Bash setup script to your Ubuntu host. Next, run the
+following to install commercially supported Docker Engine and its dependencies:
+
+```
+$ sudo apt-get update && sudo apt-get upgrade
+$ chmod 755 docker-cs-engine-deb.sh
+$ sudo ./docker-cs-engine-deb.sh
+$ sudo apt-get install docker-engine-cs
+```
+
+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
+again:
+
+```
+$ sudo usermod -a -G docker $USER
+$ exit
+```
+
+> **Note**: you may need to reboot your server to update its LTS kernel.
+
+## Installing Docker Hub Enterprise
+
+Once the commercially supported Docker Engine is installed, you can install DHE
+itself. DHE is a self-installing application built and distributed using Docker
+and the [Docker Hub](https://registry.hub.docker.com/). It is able to restart
+and reconfigure itself using the Docker socket that is bind-mounted to its
+container.
+
+
+Start installing DHE by running the "dockerhubenterprise/manager" container:
+
+```
+	$ sudo bash -c "$(sudo docker run dockerhubenterprise/manager install)"
+```
+
+> **Note**: `sudo` is needed for `dockerhubenterprise/manager` commands to
+> ensure that the Bash script is run with full access to the Docker host.
+
+You can also find this command on the "Enterprise Licenses" section of your Hub
+user profile. The command will execute a shell script that creates the needed
+directories and then runs Docker to pull DHE's images and run its containers.
+
+Depending on your internet connection, this process may take several minutes to
+complete.
+
+A successful installation will pull a large number of Docker images and should
+display output similar to:
+
+```
+$ sudo bash -c "$(sudo docker run dockerhubenterprise/manager install)"
+Unable to find image 'dockerhubenterprise/manager:latest' locally
+Pulling repository dockerhubenterprise/manager
+c46d58daad7d: Pulling image (latest) from dockerhubenterprise/manager
+c46d58daad7d: Pulling image (latest) from dockerhubenterprise/manager
+c46d58daad7d: Pulling dependent layers
+511136ea3c5a: Download complete
+fa4fd76b09ce: Pulling metadata
+fa4fd76b09ce: Pulling fs layer
+ff2996b1faed: Download complete
+...
+fd7612809d57: Pulling metadata
+fd7612809d57: Pulling fs layer
+fd7612809d57: Download complete
+c46d58daad7d: Pulling metadata
+c46d58daad7d: Pulling fs layer
+c46d58daad7d: Download complete
+c46d58daad7d: Download complete
+Status: Downloaded newer image for dockerhubenterprise/manager:latest
+Unable to find image 'dockerhubenterprise/manager:1.0.0_8ce62a61e058' locally
+Pulling repository dockerhubenterprise/manager
+c46d58daad7d: Download complete
+511136ea3c5a: Download complete
+fa4fd76b09ce: Download complete
+1c8294cc5160: Download complete
+117ee323aaa9: Download complete
+2d24f826cb16: Download complete
+33bfc1956932: Download complete
+48f0dd6c9414: Download complete
+65c30f72ecb2: Download complete
+d4b29764d0d3: Download complete
+5654f4fe5384: Download complete
+9b9faa6ecd11: Download complete
+0c275f56ca5c: Download complete
+ff2996b1faed: Download complete
+fd7612809d57: Download complete
+Status: Image is up to date for dockerhubenterprise/manager:1.0.0_8ce62a61e058
+INFO  [1.0.0_8ce62a61e058] Attempting to connect to docker engine dockerHost="unix:///var/run/docker.sock"
+INFO  [1.0.0_8ce62a61e058] Running install command
+<...output truncated...>
+Creating container docker_hub_enterprise_load_balancer with docker daemon unix:///var/run/docker.sock
+Starting container docker_hub_enterprise_load_balancer with docker daemon unix:///var/run/docker.sock
+Bringing up docker_hub_enterprise_log_aggregator.
+Creating container docker_hub_enterprise_log_aggregator with docker daemon unix:///var/run/docker.sock
+Starting container docker_hub_enterprise_log_aggregator with docker daemon unix:///var/run/docker.sock
+$ docker ps
+CONTAINER ID        IMAGE                                                   COMMAND                CREATED             STATUS         PORTS                                      NAMES
+0168f37b6221        dockerhubenterprise/log-aggregator:1.0.0_8ce62a61e058   "log-aggregator"       4 seconds ago       Up 4 seconds                                              docker_hub_enterprise_log_aggregator
+b51c73bebe8b        dockerhubenterprise/nginx:1.0.0_8ce62a61e058            "nginxWatcher"         4 seconds ago       Up 4 seconds   0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp   docker_hub_enterprise_load_balancer
+e8327864356b        dockerhubenterprise/admin-server:1.0.0_8ce62a61e058     "server"               5 seconds ago       Up 5 seconds   80/tcp                                     docker_hub_enterprise_admin_server
+52885a6e830a        dockerhubenterprise/auth_server:alpha-a5a2af8a555e      "garant --authorizat   6 seconds ago       Up 5 seconds   8080/tcp
+```
+
+Once this process completes, you should be able to manage and configure your DHE
+instance by pointing your browser to `https://<host-ip>/`.
+
+Your browser will warn you that this is an unsafe site, with a self-signed,
+untrusted certificate. This is normal and expected; allow this connection
+temporarily.
+
+### Setting the DHE Domain Name
+
+The DHE Administrator site will also warn that the "Domain Name" is not set. Go
+to the "Settings" tab, and set the "Domain Name" to the full host-name of your
+DHE server.
+Hitting the "Save and Restart DHE Server" button will generate a new certificate, which will be used
+by both the DHE Administrator web interface and the DHE Registry server.
+
+After the server restarts, you will again need to allow the connection to the untrusted DHE web admin site.
+
+![http settings page</admin/settings#http>](../assets/admin-settings-http-unlicensed.png)
+
+Lastly, you will see a warning notifying you that this instance of DHE is
+unlicensed. You'll correct this in the next step.
+
+### Add your license
+
+The DHE registry services will not start until you add your license.
+To do that, you'll first download your license from the Docker Hub and then
+upload it to your DHE web admin server. Follow these steps:
+
+1. If needed, log back into the [Docker Hub](https://hub.docker.com)
+   using the user-name you used when obtaining your license. Go to "Settings" (in
+   the menu under your user-name, top right) to get to your account settings, and
+   then click on "Enterprise Licenses" in the side bar at left.
+
+2. You'll see a list of available licenses. Click on the download button to
+   obtain the license file you'd like to use.
+   ![Download DHE license](../assets/docker-hub-org-enterprise-license.png)
+
+3. Next, go to your DHE instance in your browser and click on the Settings tab
+   and then the "License" tab. Click on the "Upload license file" button, which
+   will open a standard file browser. Locate and select the license file you
+   downloaded in step 2, above. Approve the selection to close the dialog.
+   ![http settings page</admin/settings#license>](../assets/admin-settings-license.png)
+
+4. Click the "Save and Restart DHE" button, which will quit DHE and then restart it, registering
+   the new license.
+
+5. Verify the acceptance of the license by confirming that the "unlicensed copy"
+warning is no longer present.
+
+### Securing DHE
+
+Securing DHE is **required**. You will not be able to push or pull from DHE until you secure it.
+
+There are several options and methods for securing DHE. For more information,
+see the [configuration documentation](./configuration.md#security)
+
+### Using DHE to push and pull images
+
+Now that you have DHE configured with a "Domain Name" and have your client
+Docker daemons configured with the required security settings, you can test your
+setup by following the instructions for
+[Using DHE to Push and pull images](./userguide.md#using-dhe-to-push-and-pull-images).
+
+### DHE web interface and registry authentication
+
+By default, there is no authentication set on either the DHE web admin
+interface or the DHE registry. You can restrict access using an in-DHE
+configured set of users (and passwords), or you can configure DHE to use LDAP-
+based authentication.
+
+See [DHE Authentication settings](./configuration.md#authentication) for more
+details.
+
+# Upgrading
+
+DHE has been designed to allow on-the-fly software upgrades. Start by
+clicking on the "System Health" tab. In the upper, right-hand side of the
+dashboard, below the navigation bar, you'll see the currently installed version
+(e.g., `Current Version: 0.1.12345`).
+
+If your DHE instance is the latest available, you will also see the message:
+"System Up to Date."
+
+If there is an upgrade available, you will see the message "System Update
+Available!" alongside a button labeled "Update to Version X.XX". To upgrade, DHE
+will pull new DHE container images from the Docker Hub. If you have not already
+connected to Docker Hub, DHE will prompt you to log in.
+
+The upgrade process requires a small amount of downtime to complete. To complete
+the upgrade, DHE will:
+* Connect to the Docker Hub to pull new container images with the new version of
+DHE.
+* Deploy those containers
+* Shut down the old containers
+* Resolve any necessary links/urls.
+
+Assuming you have a decent internet connection, the entire upgrade process
+should complete within a few minutes.
+
+## Next Steps
+
+For information on configuring DHE for your environment, take a look at the
+[Configuration instructions](./configuration.md).
+

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

@@ -0,0 +1,308 @@
+page_title: Docker Hub Enterprise: Quick-start: Basic Workflow
+page_description: Brief tutorial on the basics of Docker Hub Enterprise user workflow
+page_keywords: docker, documentation, about, technology, understanding, enterprise, hub, registry, image, repository
+
+
+# Docker Hub Enterprise Quick Start: Basic User Workflow
+
+## Overview
+
+This Quick Start Guide will give you a hands-on look at the basics of using
+Docker Hub Enterprise (DHE), Docker’s on-premise image storage application.
+This guide will walk you through using DHE to complete a typical, and critical,
+part of building a development pipeline: setting up a Jenkins instance. Once you
+complete the task, you should have a good idea of how DHE works and how it might
+be useful to you.
+
+Specifically, this guide demonstrates the process of retrieving the
+[official Docker image for Jenkins](https://registry.hub.docker.com/_/jenkins/),
+customizing it to suit your needs, and then hosting it on your private instance
+of DHE located inside your enterprise’s firewalled environment. Your developers
+will then be able to retrieve the custom Jenkins image in order to use it to
+build CI/CD infrastructure for their projects, no matter the platform they’re
+working from, be it a laptop, a VM, or a cloud provider.
+
+The guide will walk you through the following steps:
+
+1. Pulling the official Jenkins image from the public Docker Hub
+2. Customizing the Jenkins image to suit your needs
+3. Pushing the customized image to DHE
+4. Pulling the customized image from DHE
+4. Launching a container from the custom image
+5. Using the new Jenkins container
+
+You should be able to complete this guide in about thirty minutes.
+
+> **Note:** This guide assumes you have installed a working instance of DHE
+> reachable at dhe.yourdomain.com. If you need help installing and configuring
+> DHE, please consult the
+[installation instructions](./install.md).
+
+
+## Pulling the official Jenkins image
+
+> **Note:** This guide assumes you are familiar with basic Docker concepts such
+> as images, containers, and registries. If you need to learn more about Docker
+> 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
+the
+[`docker pull`](https://docs.docker.com/reference/commandline/cli/#pull)
+command to pull the public Jenkins image.
+
+    $ docker pull jenkins
+
+> **Note:** This guide assumes you can run Docker commands from a machine where
+> 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 images
+    REPOSITORY  TAG     IMAGE ID      CREATED      VIRTUAL SIZE
+    jenkins     latest  1a7cc22b0ee9  6 days ago   662 MB
+
+> **Note:** Because the `pull` command did not specify any tags, it will pull
+> the latest version of the public Jenkins image. If your enterprise environment
+> requires you to use a specific version, add the tag for the version you need
+> (e.g., `jenkins:1.565`).
+
+## Customizing the Jenkins image
+
+Now that you have a local copy of the Jenkins image, you’ll customize it so that
+the containers it builds will integrate with your infrastructure. To do this,
+you’ll create a custom Docker image that adds a Jenkins plugin that provides
+fine grained user management. You’ll also configure Jenkins to be more secure by
+disabling HTTP access and forcing it to use HTTPS.
+You’ll do this by using a `Dockerfile` and the `docker build` command.
+
+> **Note:** These are obviously just a couple of examples of the many ways you
+> can modify and configure Jenkins. Feel free to add or substitute whatever
+> customization is necessary to run Jenkins in your environment.
+
+### Creating a `build` context
+
+In order to add the new plugin and configure HTTPS access to the custom Jenkins
+image, you need to:
+
+1. Create text file that defines the new plugin
+2. Create copies of the private key and certificate
+
+All of the above files need to be in the same directory as the Dockerfile you
+will create in the next step.
+
+1. Create a build directory called `build`, and change to that new directory:
+
+    $ mkdir build && cd build
+
+In this directory, create a new file called `plugins` and add the following
+line:
+
+    role-strategy:2.2.0
+
+(The plugin version used above was the latest version at the time of writing.)
+
+2. You will also need to make copies of the server’s private key and certificate. Give the copies the following names — `https.key` and `https.pem`.
+
+> **Note:** Because creating new keys varies widely by platform and
+> implementation, this guide won’t cover key generation. We assume you have
+> access to existing keys. If you don’t have access, or can’t generate keys
+> yourself, feel free to skip the steps involving them and HTTPS config. The
+> guide will still walk you through building a custom Jenkins image and pushing
+> and pulling that image using DHE.
+
+### Creating a Dockerfile
+
+In the same directory as the `plugins` file and the private key and certificate,
+create a new [`Dockerfile`](https://docs.docker.com/reference/builder/) with the
+following contents:
+
+     FROM jenkins
+
+     #New plugins must be placed in the plugins file
+     COPY plugins /usr/share/jenkins/plugins
+
+     #The plugins.sh script will install new plugins
+     RUN /usr/local/bin/plugins.sh /usr/share/jenkins/plugins
+
+     #Copy private key and cert to image
+     COPY https.pem /var/lib/jenkins/cert
+     COPY https.key /var/lib/jenkins/pk
+
+     #Configure HTTP off and HTTPS on, using port 1973
+    ENV JENKINS_OPTS --httpPort=-1 --httpsPort=1973 --httpsCertificate=/var/lib/jenkins/cert --httpsPrivateKey=/var/lib/jenkins/pk
+
+The first `COPY` instruction in the above will copy the `plugin` file created
+earlier into the `/usr/share/jenkins` directory within the custom image you are
+defining with the `Dockerfile`.
+
+The `RUN` instruction will execute the `/usr/local/bin/plugins.sh` script with
+the newly copied `plugins` file, which will install the listed plugin.
+
+The next two `COPY` instructions copy the server’s private key and certificate
+into the required directories within the new image.
+
+The `ENV` instruction creates an environment variable called `JENKINS_OPT` in
+the image you are about to create. This environment variable will be present in
+any containers launched form the image and contains the required settings to
+tell Jenkins to disable HTTP and operate over HTTPS.
+
+> **Note:** You can specify any valid port number as part of the `JENKINS_OPT`
+> environment variable declared above. The value `1973` used in the example is
+> arbitrary.
+
+The `Dockerfile`, the `plugins` file, as well as the private key and
+certificate, must all be in the same directory because the `docker build`
+command uses the directory that contains the `Dockerfile` as its “build
+context”. Only files contained within that “build context” will be included in
+the image being built.
+
+### Building your custom image
+
+Now that the `Dockerfile`, the `plugins` file, and the files required for HTTPS
+operation are created in your current working directory, you can build your
+custom image using the
+[`docker build` command](https://docs.docker.com/reference/commandline/cli/#build):
+
+    docker build -t dhe.yourdomain.com/ci-infrastructure/jnkns-img .
+
+> **Note:** Don’t miss the period (`.`) at the end of the command above. This
+> tells the `docker build` command to use the current working directory as the
+> "build context".
+
+This command will build a new Docker image called `jnkns-img` which is based on
+the public Jenkins image you pulled earlier, but contains all of your
+customization.
+
+Please note the use of the `-t` flag in the `docker build` command above. The
+`-t` flag lets you  tag an image so it can be pushed to a custom repository. In
+the example above, the new image is tagged so it can be pushed to the
+`ci-infrastructure` Repository within the `dhe.yourdomain.com` registry (your
+local DHE instance). This will be important when you need to `push` the
+customized image to DHE later.
+
+A `docker images` command will now show the custom image alongside the Jenkins
+image pulled earlier:
+
+    $ sudo docker images
+    REPOSITORY   TAG    IMAGE ID    CREATED    VIRTUAL SIZE
+    dhe.yourdomain.com/ci-infrastructure/jnkns-img    latest    fc0ab3008d40    2 minutes ago    674.5 MB
+    jenkins    latest    1a7cc22b0ee9    6 days ago    662 MB
+
+## Pushing to Docker Hub Enterprise
+
+Now that you’ve create 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
+    511136ea3c5a: Image successfully pushed
+    848d84b4b2ab: Image successfully pushed
+    71d9d77ae89e: Image already exists
+    <truncated ouput...>
+    492ed3875e3e: Image successfully pushed
+    fc0ab3008d40: Image successfully pushed
+
+You can view the traffic throughput while the custom image is being pushed from
+the `System Health` tab in DHE:
+
+![DHE console push throughput](../assets/console-push.png)
+
+Once the image is successfully pushed, it can be downloaded, or pulled, by any
+Docker host that has access to DHE.
+
+## Pulling from Docker Hub Enterprise
+To pull the `jnkns-img` image from DHE, run the
+[`docker pull`](https://docs.docker.com/reference/commandline/cli/#pull)
+command from any Docker Host that has access to your DHE instance:
+
+    $ docker pull dhe.yourdomain.com/ci-infrastructure/jnkns-img
+    latest: Pulling from dhe.yourdomain.com/ci-infrastructure/jnkns-img
+    511136ea3c5a: Pull complete
+    848d84b4b2ab: Pull complete
+    71d9d77ae89e: Pull complete
+    <truncated ouput...>
+    492ed3875e3e: Pull complete
+    fc0ab3008d40: Pull complete
+    dhe.yourdomain.com/ci-infrastructure/jnkns-img:latest: The image you are pulling has been verified. Important: image verification is a tech preview feature and should not be relied on to provide security.
+    Status: Downloaded newer image for dhe.yourdomain.com/ci-infrastructure/jnkns-img:latest
+
+You can view the traffic throughput while the custom image is being pulled from
+the `System Health` tab in DHE:
+
+![DHE console pull throughput](../assets/console-pull.png)
+
+Now that the `jnkns-img` image has been pulled locally from DHE, you can view it
+in the output of the `docker images` command:
+
+     $ docker images
+    REPOSITORY     TAG    IMAGE ID    CREATED    VIRTUAL SIZE
+    dhe.yourdomain.com/ci-infrastructure/jnkns-img    latest  fc0ab3008d40    8 minutes ago    674.5 MB
+
+## Launching a custom Jenkins container
+
+Now that you’ve successfully pulled the customized Jenkins image from DHE, you
+can create a container from it with the
+[`docker run` command](https://docs.docker.com/reference/commandline/cli/#run):
+
+
+    $ docker run -p 1973:1973 --name jenkins01 dhe.yourdomain.com/ci-infrastructure/jnkns-img
+    /usr/share/jenkins/ref/init.groovy.d/tcp-slave-angent-port.groovy
+     /usr/share/jenkins/ref/init.groovy.d/tcp-slave-angent-port.groovy -> init.groovy.d/tcp-slave-angent-port.groovy
+    copy init.groovy.d/tcp-slave-angent-port.groovy to JENKINS_HOME
+    /usr/share/jenkins/ref/plugins/role-strategy.hpi
+     /usr/share/jenkins/ref/plugins/role-strategy.hpi -> plugins/role-strategy.hpi
+    copy plugins/role-strategy.hpi to JENKINS_HOME
+    /usr/share/jenkins/ref/plugins/dockerhub.hpi
+     /usr/share/jenkins/ref/plugins/dockerhub.hpi -> plugins/dockerhub.hpi
+    copy plugins/dockerhub.hpi to JENKINS_HOME
+    <truncated output...>
+    INFO: Jenkins is fully up and running
+
+> **Note:** The `docker run` command above maps port 1973 in the container
+> through to port 1973 on the host. This is the HTTPS port you specified in the
+> Dockerfile earlier. If you specified a different HTTPS port in your
+> Dockerfile, you will need to substitute this with the correct port numbers for
+> your environment.
+
+You can view the newly launched a container, called `jenkins01`, using the
+[`docker ps` command](https://docs.docker.com/reference/commandline/cli/#ps):
+
+    $ docker ps
+    CONTAINER ID     IMAGE     COMMAND     CREATED      STATUS  ...PORTS     NAMES
+    2e5d2f068504    dhe.yourdomain.com/ci-infrastructure/jnkns-img:latest    "/usr/local/bin/jenk     About a minute ago     Up About a minute     50000/tcp, 0.0.0.0:1973->1973/tcp     jenkins01
+
+
+## Accessing the new Jenkins container
+
+The previous `docker run` command mapped port `1973` on the container to port
+`1973` on the Docker host, so the Jenkins Web UI can be accessed at
+`https://<docker-host>:1973` (Don’t forget the `s` at the end of `https`.)
+
+> **Note:** If you are using a self-signed certificate, you may get a security
+> warning from your browser telling you that the certificate is self-signed and
+> not trusted. You may wish to add the certificate to the trusted store in order
+> to prevent further warnings in the future.
+
+![Jenkins landing page](../assets/jenkins-ui.png)
+
+From within the Jenkins Web UI, navigate to `Manage Jenkins` (on the left-hand
+pane) > `Manage Plugins` > `Installed`. The  `Role-based Authorization Strategy`
+plugin should be present with the `Uninstall` button available to the right.
+
+![Jenkins plugin manager](../assets/jenkins-plugins.png)
+
+In another browser session, try to access Jenkins via the default HTTP port 8080
+— `http://<docker-host>:8080`. This should result in a “connection timeout,”
+showing that Jenkins is not available on its default port 8080 over HTTP.
+
+This demonstration shows your Jenkins image has been configured correctly for
+HTTPS access, your new plugin was added and is ready for use, and HTTP access
+has been disabled. At this point, any member of your team can use `docker pull`
+to access the image from your DHE instance, allowing them to access a
+configured, secured Jenkins instance that can run on any infrastructure.
+
+## Next Steps
+
+For more information on using DHE, take a look at the
+[User's Guide](./userguide.md).

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

@@ -0,0 +1,14 @@
+page_title: Docker Hub Enterprise: Support
+page_description: Commercial Support
+page_keywords: docker, documentation, about, technology, understanding, enterprise, hub, registry, support
+
+# Commercial Support
+
+Purchasing a DHE License or Commercial Support subscription means your questions
+and issues about DHE will receive prioritized support.
+You can file a ticket through [email](mailto:support@docker.com) from your
+company email address, or visit our [support site](https://support.docker.com).
+In either case, you'll need to verify your email address, and then you can
+communicate with the support team either by email or web interface.
+
+**The availability of support depends on your [support subscription](https://www.docker.com/enterprise/support/)**

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

@@ -1,9 +0,0 @@
-page_title: Using Docker Hub Enterprise
-page_description: Docker Hub Enterprise
-page_keywords: docker hub enterprise
-
-# Docker Hub Enterprise
-
-Documenation coming soon.
-
-

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

@@ -0,0 +1,130 @@
+page_title: Docker Hub Enterprise: User guide
+page_description: Documentation describing basic use of Docker Hub Enterprise
+page_keywords: docker, documentation, about, technology, hub, enterprise
+
+
+# Docker Hub Enterprise User's Guide
+
+This guide covers tasks and functions a user of Docker Hub Enterprise (DHE) will
+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
+
+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.
+
+> **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
+
+
+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.
+
+    `$ docker pull hello-world`
+
+2. List your available images.
+
+        $ docker images
+        REPOSITORY     TAG     IMAGE ID      CREATED       VIRTUAL SIZE
+        hello-world    latest  e45a5af57b00  3 months ago  910 B
+
+    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.
+
+    `$ docker push dhe.yourdomain.com/demouser/hello-mine:latest`
+
+6. Set up a test of DHE by removing all images from your local environment:
+
+    `$ docker rmi -f $(docker images -q -a)`
+
+    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.
+
+        $ 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
+        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.
+
+        $ docker images
+        REPOSITORY                           TAG     IMAGE ID      CREATED       VIRTUAL SIZE
+        dhe.yourdomain.com/demouser/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
+
+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).
+
+
+<!--TODO:
+
+* 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 -->