diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index df9d95997c..e425175f61 100644 --- a/docs/mkdocs.yml +++ b/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/index.md', '**HIDDEN**' ] -#- ['docker-hub-enterprise/install-config.md', 'Docker Hub Enterprise', 'Installation and Configuration' ] -#- ['docker-hub-enterprise/usage.md', 'Docker Hub Enterprise', 'User Guide' ] +# Docker Hub Enterprise: +- ['docker-hub-enterprise/index.md', 'Docker Hub Enterprise', 'Overview' ] +- ['docker-hub-enterprise/quick-start.md', 'Docker Hub Enterprise', 'Quick Start: Basic Workflow' ] +- ['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/software-required.md', 'Contributor Guide', 'Get required software'] -- ['project/set-up-git.md', 'Contributor Guide', 'Configure Git for contributing'] -- ['project/set-up-dev-env.md', 'Contributor Guide', 'Work with a development container'] -- ['project/test-and-docs.md', 'Contributor Guide', 'Run tests and test documentation'] -- ['project/make-a-contribution.md', 'Contributor Guide', 'Understand contribution workflow'] -- ['project/find-an-issue.md', 'Contributor Guide', 'Find an issue'] -- ['project/work-issue.md', 'Contributor Guide', 'Work on an issue'] -- ['project/create-pr.md', 'Contributor Guide', 'Create a pull request'] -- ['project/review-pr.md', 'Contributor Guide', 'Participate in the PR review'] -- ['project/advanced-contributing.md', 'Contributor Guide', 'Advanced contributing'] -- ['project/get-help.md', 'Contributor Guide', 'Where to get help'] -- ['project/coding-style.md', 'Contributor Guide', 'Coding style guide'] -- ['project/doc-style.md', 'Contributor Guide', 'Documentation style guide'] +- ['project/who-written-for.md', 'Contribute', 'README first'] +- ['project/software-required.md', 'Contribute', 'Get required software'] +- ['project/set-up-git.md', 'Contribute', 'Configure Git for contributing'] +- ['project/set-up-dev-env.md', 'Contribute', 'Work with a development container'] +- ['project/test-and-docs.md', 'Contribute', 'Run tests and test documentation'] +- ['project/make-a-contribution.md', 'Contribute', 'Understand contribution workflow'] +- ['project/find-an-issue.md', 'Contribute', 'Find an issue'] +- ['project/work-issue.md', 'Contribute', 'Work on an issue'] +- ['project/create-pr.md', 'Contribute', 'Create a pull request'] +- ['project/review-pr.md', 'Contribute', 'Participate in the PR review'] +- ['project/advanced-contributing.md', 'Contribute', 'Advanced contributing'] +- ['project/get-help.md', 'Contribute', 'Where to get help'] +- ['project/coding-style.md', 'Contribute', 'Coding style guide'] +- ['project/doc-style.md', 'Contribute', 'Documentation style guide'] diff --git a/docs/sources/docker-hub-enterprise/admin-metrics.png b/docs/sources/docker-hub-enterprise/admin-metrics.png new file mode 100644 index 0000000000..21a8f74a7c Binary files /dev/null and b/docs/sources/docker-hub-enterprise/admin-metrics.png differ diff --git a/docs/sources/docker-hub-enterprise/admin-settings-http.png b/docs/sources/docker-hub-enterprise/admin-settings-http.png new file mode 100644 index 0000000000..77df71f7ea Binary files /dev/null and b/docs/sources/docker-hub-enterprise/admin-settings-http.png differ diff --git a/docs/sources/docker-hub-enterprise/admin.png b/docs/sources/docker-hub-enterprise/admin.png new file mode 100644 index 0000000000..54826e5658 Binary files /dev/null and b/docs/sources/docker-hub-enterprise/admin.png differ diff --git a/docs/sources/docker-hub-enterprise/adminguide.md b/docs/sources/docker-hub-enterprise/adminguide.md new file mode 100644 index 0000000000..d471041675 --- /dev/null +++ b/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](../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](../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 `-`, 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://: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). diff --git a/docs/sources/docker-hub-enterprise/assets/admin-logs.png b/docs/sources/docker-hub-enterprise/assets/admin-logs.png new file mode 100644 index 0000000000..76f0d19a80 Binary files /dev/null and b/docs/sources/docker-hub-enterprise/assets/admin-logs.png differ diff --git a/docs/sources/docker-hub-enterprise/assets/admin-metrics.png b/docs/sources/docker-hub-enterprise/assets/admin-metrics.png new file mode 100644 index 0000000000..ccec72a31a Binary files /dev/null and b/docs/sources/docker-hub-enterprise/assets/admin-metrics.png differ diff --git a/docs/sources/docker-hub-enterprise/assets/admin-settings-authentication-basic.png b/docs/sources/docker-hub-enterprise/assets/admin-settings-authentication-basic.png new file mode 100644 index 0000000000..ef9dfe3513 Binary files /dev/null and b/docs/sources/docker-hub-enterprise/assets/admin-settings-authentication-basic.png differ diff --git a/docs/sources/docker-hub-enterprise/assets/admin-settings-authentication-ldap.png b/docs/sources/docker-hub-enterprise/assets/admin-settings-authentication-ldap.png new file mode 100644 index 0000000000..112a15c361 Binary files /dev/null and b/docs/sources/docker-hub-enterprise/assets/admin-settings-authentication-ldap.png differ diff --git a/docs/sources/docker-hub-enterprise/assets/admin-settings-authentication.png b/docs/sources/docker-hub-enterprise/assets/admin-settings-authentication.png new file mode 100644 index 0000000000..83cba1287c Binary files /dev/null and b/docs/sources/docker-hub-enterprise/assets/admin-settings-authentication.png differ diff --git a/docs/sources/docker-hub-enterprise/assets/admin-settings-http-unlicensed.png b/docs/sources/docker-hub-enterprise/assets/admin-settings-http-unlicensed.png new file mode 100644 index 0000000000..27ce98b27d Binary files /dev/null and b/docs/sources/docker-hub-enterprise/assets/admin-settings-http-unlicensed.png differ diff --git a/docs/sources/docker-hub-enterprise/assets/admin-settings-http.png b/docs/sources/docker-hub-enterprise/assets/admin-settings-http.png new file mode 100644 index 0000000000..d860c5088d Binary files /dev/null and b/docs/sources/docker-hub-enterprise/assets/admin-settings-http.png differ diff --git a/docs/sources/docker-hub-enterprise/assets/admin-settings-license.png b/docs/sources/docker-hub-enterprise/assets/admin-settings-license.png new file mode 100644 index 0000000000..488f212008 Binary files /dev/null and b/docs/sources/docker-hub-enterprise/assets/admin-settings-license.png differ diff --git a/docs/sources/docker-hub-enterprise/assets/admin-settings-security.png b/docs/sources/docker-hub-enterprise/assets/admin-settings-security.png new file mode 100644 index 0000000000..81d375040e Binary files /dev/null and b/docs/sources/docker-hub-enterprise/assets/admin-settings-security.png differ diff --git a/docs/sources/docker-hub-enterprise/assets/admin-settings-storage.png b/docs/sources/docker-hub-enterprise/assets/admin-settings-storage.png new file mode 100644 index 0000000000..9aea039c68 Binary files /dev/null and b/docs/sources/docker-hub-enterprise/assets/admin-settings-storage.png differ diff --git a/docs/sources/docker-hub-enterprise/assets/admin-settings.png b/docs/sources/docker-hub-enterprise/assets/admin-settings.png new file mode 100644 index 0000000000..699e722e93 Binary files /dev/null and b/docs/sources/docker-hub-enterprise/assets/admin-settings.png differ diff --git a/docs/sources/docker-hub-enterprise/assets/console-pull.png b/docs/sources/docker-hub-enterprise/assets/console-pull.png new file mode 100755 index 0000000000..57f264f4ea Binary files /dev/null and b/docs/sources/docker-hub-enterprise/assets/console-pull.png differ diff --git a/docs/sources/docker-hub-enterprise/assets/console-push.png b/docs/sources/docker-hub-enterprise/assets/console-push.png new file mode 100755 index 0000000000..25acdc18c3 Binary files /dev/null and b/docs/sources/docker-hub-enterprise/assets/console-push.png differ diff --git a/docs/sources/docker-hub-enterprise/assets/docker-hub-org-enterprise-license-CSDE-dropdown.png b/docs/sources/docker-hub-enterprise/assets/docker-hub-org-enterprise-license-CSDE-dropdown.png new file mode 100644 index 0000000000..49dbfab874 Binary files /dev/null and b/docs/sources/docker-hub-enterprise/assets/docker-hub-org-enterprise-license-CSDE-dropdown.png differ diff --git a/docs/sources/docker-hub-enterprise/assets/docker-hub-org-enterprise-license.png b/docs/sources/docker-hub-enterprise/assets/docker-hub-org-enterprise-license.png new file mode 100644 index 0000000000..3c70b747c6 Binary files /dev/null and b/docs/sources/docker-hub-enterprise/assets/docker-hub-org-enterprise-license.png differ diff --git a/docs/sources/docker-hub-enterprise/assets/jenkins-plugins.png b/docs/sources/docker-hub-enterprise/assets/jenkins-plugins.png new file mode 100755 index 0000000000..667e98b55b Binary files /dev/null and b/docs/sources/docker-hub-enterprise/assets/jenkins-plugins.png differ diff --git a/docs/sources/docker-hub-enterprise/assets/jenkins-ui.png b/docs/sources/docker-hub-enterprise/assets/jenkins-ui.png new file mode 100755 index 0000000000..6c8bd5f722 Binary files /dev/null and b/docs/sources/docker-hub-enterprise/assets/jenkins-ui.png differ diff --git a/docs/sources/docker-hub-enterprise/configuration.md b/docs/sources/docker-hub-enterprise/configuration.md new file mode 100644 index 0000000000..6050da401a --- /dev/null +++ b/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](../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://<dhe-host>/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](../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 | 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 | 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 | 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](../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](../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](../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). + diff --git a/docs/sources/docker-hub-enterprise/index.md b/docs/sources/docker-hub-enterprise/index.md new file mode 100644 index 0000000000..c14bf9280f --- /dev/null +++ b/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. + diff --git a/docs/sources/docker-hub-enterprise/install-config.md b/docs/sources/docker-hub-enterprise/install-config.md deleted file mode 100644 index 81fa3041ef..0000000000 --- a/docs/sources/docker-hub-enterprise/install-config.md +++ /dev/null @@ -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. - diff --git a/docs/sources/docker-hub-enterprise/install.md b/docs/sources/docker-hub-enterprise/install.md new file mode 100644 index 0000000000..84f9a321b3 --- /dev/null +++ b/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:///`. + +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](../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](../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). + diff --git a/docs/sources/docker-hub-enterprise/quick-start.md b/docs/sources/docker-hub-enterprise/quick-start.md new file mode 100644 index 0000000000..a813deb076 --- /dev/null +++ b/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 + + 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 + + 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 + + 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://: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://: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). diff --git a/docs/sources/docker-hub-enterprise/support.md b/docs/sources/docker-hub-enterprise/support.md new file mode 100644 index 0000000000..ed60748a3a --- /dev/null +++ b/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/)** diff --git a/docs/sources/docker-hub-enterprise/usage.md b/docs/sources/docker-hub-enterprise/usage.md deleted file mode 100644 index 252223ef70..0000000000 --- a/docs/sources/docker-hub-enterprise/usage.md +++ /dev/null @@ -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. - - diff --git a/docs/sources/docker-hub-enterprise/userguide.md b/docs/sources/docker-hub-enterprise/userguide.md new file mode 100644 index 0000000000..6d329722de --- /dev/null +++ b/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 ` (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). + + +