commit 54b3642abbfe188b12dbef54e85b7bf82066ecf1 Author: Mary Anthony Date: Sun Jun 7 18:58:42 2015 -0700 Updating for hugo Updating the sed tasks Updating image to pull Signed-off-by: Mary Anthony diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000000..3b028a509a --- /dev/null +++ b/Dockerfile @@ -0,0 +1,24 @@ +FROM docs/base:hugo +MAINTAINER Mary Anthony (@moxiegirl) + +# To get the git info for this repo +COPY . /src + +COPY . /docs/content/dhe/ + +# Sed to process GitHub Markdown +# 1-2 Remove comment code from metadata block +# 3 Remove .md extension from link text +# 4 Change ](/ to ](/project/ in links +# 5 Change ](word) to ](/project/word) +# 6 Change ](../../ to ](/project/ +# 7 Change ](../ to ](/project/word) +# +# +RUN find /docs/content/dhe -type f -name "*.md" -exec sed -i.old \ + -e '/^/g' \ + -e '/^/g' \ + -e 's/\([(]\)\(.*\)\(\.md\)/\1\2/g' \ + -e 's/\(\]\)\([(]\)\(\/\)/\1\2\/dhe\//g' \ + -e 's/\(\][(]\)\([A-z]*[)]\)/\]\(\/dhe\/\2/g' \ + -e 's/\(\][(]\)\(\.\.\/\)/\1\/dhe\//g' {} \; \ No newline at end of file diff --git a/Makefile b/Makefile new file mode 100644 index 0000000000..021e8f6e5e --- /dev/null +++ b/Makefile @@ -0,0 +1,55 @@ +.PHONY: all binary build cross default docs docs-build docs-shell shell test test-unit test-integration test-integration-cli test-docker-py validate + +# env vars passed through directly to Docker's build scripts +# to allow things like `make DOCKER_CLIENTONLY=1 binary` easily +# `docs/sources/contributing/devenvironment.md ` and `project/PACKAGERS.md` have some limited documentation of some of these +DOCKER_ENVS := \ + -e BUILDFLAGS \ + -e DOCKER_CLIENTONLY \ + -e DOCKER_EXECDRIVER \ + -e DOCKER_GRAPHDRIVER \ + -e TESTDIRS \ + -e TESTFLAGS \ + -e TIMEOUT +# note: we _cannot_ add "-e DOCKER_BUILDTAGS" here because even if it's unset in the shell, that would shadow the "ENV DOCKER_BUILDTAGS" set in our Dockerfile, which is very important for our official builds + +# to allow `make DOCSDIR=docs docs-shell` (to create a bind mount in docs) +DOCS_MOUNT := $(if $(DOCSDIR),-v $(CURDIR)/$(DOCSDIR):/$(DOCSDIR)) + +# to allow `make DOCSPORT=9000 docs` +DOCSPORT := 8000 + +# Get the IP ADDRESS +DOCKER_IP=$(shell python -c "import urlparse ; print urlparse.urlparse('$(DOCKER_HOST)').hostname or ''") +HUGO_BASE_URL=$(shell test -z "$(DOCKER_IP)" && echo localhost || echo "$(DOCKER_IP)") +HUGO_BIND_IP=0.0.0.0 + +GIT_BRANCH := $(shell git rev-parse --abbrev-ref HEAD 2>/dev/null) +DOCKER_IMAGE := docker$(if $(GIT_BRANCH),:$(GIT_BRANCH)) +DOCKER_DOCS_IMAGE := docs-base$(if $(GIT_BRANCH),:$(GIT_BRANCH)) + + +DOCKER_RUN_DOCS := docker run --rm -it $(DOCS_MOUNT) -e AWS_S3_BUCKET -e NOCACHE + +# for some docs workarounds (see below in "docs-build" target) +GITCOMMIT := $(shell git rev-parse --short HEAD 2>/dev/null) + +default: docs + +docs: docs-build + $(DOCKER_RUN_DOCS) -p $(if $(DOCSPORT),$(DOCSPORT):)8000 -e DOCKERHOST "$(DOCKER_DOCS_IMAGE)" hugo server --port=$(DOCSPORT) --baseUrl=$(HUGO_BASE_URL) --bind=$(HUGO_BIND_IP) + +docs-draft: docs-build + $(DOCKER_RUN_DOCS) -p $(if $(DOCSPORT),$(DOCSPORT):)8000 -e DOCKERHOST "$(DOCKER_DOCS_IMAGE)" hugo server --buildDrafts="true" --port=$(DOCSPORT) --baseUrl=$(HUGO_BASE_URL) --bind=$(HUGO_BIND_IP) + + +docs-shell: docs-build + $(DOCKER_RUN_DOCS) -p $(if $(DOCSPORT),$(DOCSPORT):)8000 "$(DOCKER_DOCS_IMAGE)" bash + + +docs-build: +# ( git remote | grep -v upstream ) || git diff --name-status upstream/release..upstream/docs ./ > ./changed-files +# echo "$(GIT_BRANCH)" > GIT_BRANCH +# echo "$(AWS_S3_BUCKET)" > AWS_S3_BUCKET +# echo "$(GITCOMMIT)" > GITCOMMIT + docker build -t "$(DOCKER_DOCS_IMAGE)" . diff --git a/adminguide.md b/adminguide.md new file mode 100644 index 0000000000..1c07b08e9d --- /dev/null +++ b/adminguide.md @@ -0,0 +1,112 @@ + + + +# Docker Trusted Registry Administrator's Guide + +This guide covers tasks and functions an administrator of Docker Trusted Registry +(DTR) will need to know about, such as reporting, logging, system management, +performance metrics, etc. +For tasks DTR users need to accomplish, such as using DTR 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 DTR 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 DTR instance. You will see +log sections on this page for each service in your DTR instance. Older or newer +logs can be loaded by scrolling up or down. See below for a +[detailed explanation of the available services](#services). + +DTR's log files can be found on the host in `/usr/local/etc/dtr/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, DTR 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 DTR + +If your authenticated or public access to the DTR web interface has stopped +working, but your DTR 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_trusted_registry_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 DTR server - `http://:9999/admin/`. + +## Services + +DTR 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. + +## DTR system management + +The `dockerhubenterprise/manager` image is used to control the DTR system. This +image uses the Docker socket to orchestrate the multiple services that comprise +DTR. + + $ 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 DTR, take a look at the [Installation instructions](./install.md). diff --git a/assets/admin-logs.png b/assets/admin-logs.png new file mode 100644 index 0000000000..3221cc54da Binary files /dev/null and b/assets/admin-logs.png differ diff --git a/assets/admin-metrics.png b/assets/admin-metrics.png new file mode 100644 index 0000000000..965101fddb Binary files /dev/null and b/assets/admin-metrics.png differ diff --git a/assets/admin-settings-authentication-basic.png b/assets/admin-settings-authentication-basic.png new file mode 100644 index 0000000000..530a160db0 Binary files /dev/null and b/assets/admin-settings-authentication-basic.png differ diff --git a/assets/admin-settings-authentication-ldap.png b/assets/admin-settings-authentication-ldap.png new file mode 100644 index 0000000000..02715d3e77 Binary files /dev/null and b/assets/admin-settings-authentication-ldap.png differ diff --git a/assets/admin-settings-authentication.png b/assets/admin-settings-authentication.png new file mode 100644 index 0000000000..145102a698 Binary files /dev/null and b/assets/admin-settings-authentication.png differ diff --git a/assets/admin-settings-http-unlicensed.png b/assets/admin-settings-http-unlicensed.png new file mode 100644 index 0000000000..149be8097c Binary files /dev/null and b/assets/admin-settings-http-unlicensed.png differ diff --git a/assets/admin-settings-http.png b/assets/admin-settings-http.png new file mode 100644 index 0000000000..8c402bbccc Binary files /dev/null and b/assets/admin-settings-http.png differ diff --git a/assets/admin-settings-license.png b/assets/admin-settings-license.png new file mode 100644 index 0000000000..ab6082d9bb Binary files /dev/null and b/assets/admin-settings-license.png differ diff --git a/assets/admin-settings-security.png b/assets/admin-settings-security.png new file mode 100644 index 0000000000..5d837dc697 Binary files /dev/null and b/assets/admin-settings-security.png differ diff --git a/assets/admin-settings-storage.png b/assets/admin-settings-storage.png new file mode 100644 index 0000000000..a0359779d8 Binary files /dev/null and b/assets/admin-settings-storage.png differ diff --git a/assets/admin-settings.png b/assets/admin-settings.png new file mode 100644 index 0000000000..a900828eb9 Binary files /dev/null and b/assets/admin-settings.png differ diff --git a/assets/console-pull.png b/assets/console-pull.png new file mode 100644 index 0000000000..db93646b2e Binary files /dev/null and b/assets/console-pull.png differ diff --git a/assets/console-push.png b/assets/console-push.png new file mode 100644 index 0000000000..e5c45ef716 Binary files /dev/null and b/assets/console-push.png differ diff --git a/assets/docker-hub-org-enterprise-license-CSDE-dropdown.png b/assets/docker-hub-org-enterprise-license-CSDE-dropdown.png new file mode 100644 index 0000000000..49dbfab874 Binary files /dev/null and b/assets/docker-hub-org-enterprise-license-CSDE-dropdown.png differ diff --git a/assets/docker-hub-org-enterprise-license.png b/assets/docker-hub-org-enterprise-license.png new file mode 100644 index 0000000000..3c70b747c6 Binary files /dev/null and b/assets/docker-hub-org-enterprise-license.png differ diff --git a/assets/jenkins-plugins.png b/assets/jenkins-plugins.png new file mode 100644 index 0000000000..907146e65c Binary files /dev/null and b/assets/jenkins-plugins.png differ diff --git a/assets/jenkins-ui.png b/assets/jenkins-ui.png new file mode 100644 index 0000000000..be7b28d599 Binary files /dev/null and b/assets/jenkins-ui.png differ diff --git a/configuration.md b/configuration.md new file mode 100644 index 0000000000..8c1b78dc8a --- /dev/null +++ b/configuration.md @@ -0,0 +1,363 @@ + + + +# Configuring DTR + +## Overview + +This page will help you properly configure Docker Trusted Registry (DTR) so it can +run in your environment. + +Start with DTR 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 DTR 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 DTR 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://<dtr-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 DTR to re-generate a self-signed certificate at some +> point, you'll need to first delete `/usr/local/etc/dtr/ssl/server.pem`, and +> then restart the DTR 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, DTR requires encrypted communications via HTTPS/SSL between (a) the DTR registry and your Docker Engine(s), and (b) between your web browser and the DTR admin server. There are a few options for setting this up: + +1. You can use the self-signed certificate DTR 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 DTR](#adding-your-own-registry-certificates-to-dtr). + +On the other hand, if you choose to use the DTR-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 DTR, and install it +onto the client Docker daemon hosts as shown below. + +### Adding your own Registry certificates to DTR + +Whichever method you use to generate certificates, once you have them +you can set up your DTR 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 DTR 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 DTR certificates on each Linux distribution has +slightly different steps, as shown below. + +You can test this certificate using `curl`: + +``` +$ curl https://dtr.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/dtr/ssl/server.pem https://dtr.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=dtr.yourdomain.com + $ openssl s_client -connect $DOMAIN_NAME:443 -showcerts /dev/null | openssl x509 -outform PEM | sudo tee /usr/local/share/ca-certificates/$DOMAIN_NAME.crt + $ sudo update-ca-certificates + Updating certificates in /etc/ssl/certs... 1 added, 0 removed; done. + Running hooks in /etc/ca-certificates/update.d....done. + $ sudo service docker restart + docker stop/waiting + docker start/running, process 29291 +``` + +#### RHEL + +``` + $ export DOMAIN_NAME=dtr.yourdomain.com + $ openssl s_client -connect $DOMAIN_NAME:443 -showcerts /dev/null | openssl x509 -outform PEM | sudo tee /etc/pki/ca-trust/source/anchors/$DOMAIN_NAME.crt + $ sudo update-ca-trust + $ sudo /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 DTR server using: + +``` +$ openssl s_client -connect dtr.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 DTR +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 dtr.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 dtr.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 dtr.yourdomain.com" +``` + +Then restart the Docker daemon with `sudo /etc/init.d/docker restart`. + +## Image Storage Configuration + +DTR 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 DTR storage driver +API. + +![Storage settings page](../assets/admin-settings-storage.png) + +* *Yaml configuration file*: This file (`/usr/local/etc/dtr/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/dtr/image-storage`. The default value of this root directory is +`/local`, so the full path to it is `/var/local/dtr/image-storage/local`. + +> **Note:** +> Saving changes you've made to settings will restart the Docker Trusted Registry +> instance. The restart may cause a brief interruption for users of the image +> storage system. + +## Authentication + +The "Authentication" settings tab lets DTR administrators control access +to the DTR web admin tool and to the DTR Registry. + +The current authentication methods are `None`, `Basic` and `LDAP`. + +> **Note**: if you have issues logging into the DTR admin web interface after changing the authentication +> settings, you may need to use the [emergency access to the DTR admin web interface](./adminguide.md#Emergency-access-to-the-dtr-admin-web-interface). + +### No authentication + +No authentication means that everyone that can access your DTR web administration +site. This is not recommended for any use other than testing. + + +### Basic authentication + +The `Basic` authentication setting allows the admin to provide username/password pairs local to DTR. +Any user who can successfully authenticate can use DTR to push and pull Docker images. +You can optionally filter the list of users to a subset of just those users with access to the DTR +admin web interface. + +![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 DTR website Administrator Filter, allowing you to either +* * *Allow all authenticated users*: to log into the DTR admin web interface, or +* * *Whitelist usernames*: which allows you to restrict access to the web interface to a listed set of users. + +### LDAP authentication + +Using LDAP authentication allows you to integrate your DTR registry into your +organization's existing user and authentication database. + +As this involves existing infrastructure external to DTR and Docker, you will need to +gather the details required to configure DTR for your organization's particular LDAP +implementation. + +You can test that you have the necessary LDAP server information by using it from +inside a Docker container running on the same server as your DTR: + +> **Note**: if the LDAP server is configured to use *StartTLS*, then you need to add `-Z` to the +> `ldapsearch` command examples below. + +``` +docker run --rm -it svendowideit/ldapsearch -h -b -D -w +``` + +or if the LDAP server is set up to allow anonymous access (which means your *Search User DN* and *Search User Password* settings can remain empty): + +``` +docker run --rm -it svendowideit/ldapsearch -h -b -x +``` + +The result of these queries should be a (very) long list - if you get an authentication error, +then the details you have been given are not sufficient. + +The *User Login Attribute* key setting must match the field used in the LDAP server +for the user's login-name. On OpenLDAP, it's generally `uid`, and on Microsoft Active Directory +servers, it's `sAMAccountName`. The `ldapsearch` output above should allow you to +confirm which setting you need. + +![LDAP authentication settings page](../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 *DTR 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 DTR registry pull and push to users matching the LDAP filter, +* * *Whitelist usernames*: which allows you to restrict DTR registry pull and push to the listed set of users. +* A *DTR website Administrator filter*, allowing you to either +* * *Allow all authenticated users*: to log into the DTR admin web interface, or +* * *Filter LDAP search results*: which allows you to restrict DTR 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 DTR, take a look at the +[Support information](./support.md). + diff --git a/dhe-overview.md b/dhe-overview.md new file mode 100644 index 0000000000..691dcab7cf --- /dev/null +++ b/dhe-overview.md @@ -0,0 +1,63 @@ + + + +# Welcome to Docker Trusted Registry + +Docker Trusted Registry (DTR) 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. DTR also provides +monitoring and usage information to help you understand the workloads being +placed on it. + +Specifically, DTR provides: + +* An image registry to store, manage, and collaborate on Docker images +* Pluggable storage drivers +* Configuration options to let you run DTR in your particular enterprise +environment. +* Easy, transparent upgrades +* Logging, usage and system health metrics + +DTR 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 + +DTR is built on [version 2 of the Docker registry](https://github.com/docker/distribution). + +> **Note:** This initial release of DHE has limited access. To get access, +> you will need an account on [Docker Hub](https://hub.docker.com/). Once you're +> logged in to the Hub with your account, visit the +> [early access registration page](https://registry.hub.docker.com/earlyaccess/) +> and follow the steps there to get signed up. + +## Available Documentation + +The following documentation for DTR is available: + +* **Overview** This page. +* [**Quick Start: Basic User Workflow**](./quick-start.md) Go here to learn the +fundamentals of how DTR works and how you can set up a simple, but useful +workflow. +* [**User Guide**](./userguide.md) Go here to learn about using DTR from day to +day. +* [**Administrator Guide**](./adminguide.md) Go here if you are an administrator +responsible for running and maintaining DTR. +* [**Installation**](install.md) Go here for the steps you'll need to install +DTR and get it working. +* [**Configuration**](./configuration.md) Go here to find out details about +setting up and configuring DTR for your particular environment. +* [**Support**](./support.md) Go here for information on getting support for +DTR. + diff --git a/install.md b/install.md new file mode 100644 index 0000000000..4c215ea3ff --- /dev/null +++ b/install.md @@ -0,0 +1,366 @@ + + + +# Install Docker Trusted Registry + +This document describes the process of obtaining, installing, and securing +Docker Trusted Registry (DTR). DTR 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 [DTR Configuration page](./configuration.md). + +Specifically, installation requires completion of these steps, in order: + +1. Acquire a license by purchasing DTR or requesting a trial license. +2. Install the commercially supported Docker Engine. +3. Install DTR +4. Add your license to your DTR instance + +> **Note:** This initial release of DHE has limited access. To get access, +> you will need an account on [Docker Hub](https://hub.docker.com/). Once you're +> logged in to the Hub with your account, visit the +> [early access registration page](https://registry.hub.docker.com/earlyaccess/) +> and follow the steps there to get signed up. + +## Licensing + +In order to run DTR, you will need to acquire a license, either by purchasing +DTR 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 DTR. + +## Prerequisites + +DTR 1.0.1 requires the following: + +* Commercially supported Docker Engine 1.6.1 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 DTR 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 DTR management containers, allowing +DTR to manage itself and its updates. For this reason, your DTR 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 DTR +container port mapping. + +* You will also need the Docker Hub user-name and password used when obtaining +the DTR license (or the user-name of an administrator of the Hub organization +that obtained an Enterprise license). + +## Installing the Commercially Supported Docker Engine + +Since DTR 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 +$ sudo apt-get install -y linux-image-extra-virtual +$ sudo reboot +$ chmod 755 docker-cs-engine-deb.sh +$ sudo ./docker-cs-engine-deb.sh +$ sudo apt-get install docker-engine-cs +``` +Lastly, confirm Docker is running with `sudo service docker start`. + +In order to simplify using Docker, you can get non-sudo access to the Docker +socket by adding your user to the `docker` group, then logging out and back in +again: + +``` +$ sudo usermod -a -G docker $USER +$ exit +``` + +> **Note**: you may need to reboot your server to update its LTS kernel. + +## Upgrading the Commercially Supported Docker Engine + +CS Docker Engine 1.6.1 contains fixes to security vulnerabilities, + and customers should upgrade to it immediately. + +> **Note**: If you have CS Docker Engine 1.6.0 installed, it must be upgraded; + however, due to compatibility issues, [DTR must be upgraded](#upgrading-docker-hub-enterprise) + first. + +The CS Docker Engine installation script set up the RHEL/Ubuntu package repositories, +so upgrading the Engine only requires you to run the update commands on your server. + +### RHEL 7.0/7.1 upgrade + +The following commands will stop the running DHE, upgrade CS Docker Engine, +and then start DHE again: + +``` + $ sudo bash -c "$(sudo docker run docker/trusted-registry stop)" + $ sudo yum update + $ sudo systemctl daemon-reload && sudo systemctl restart docker + $ sudo bash -c "$(sudo docker run docker/trusted-registry start)" +``` + +### Ubuntu 14.04 LTS upgrade + +The following commands will stop the running DHE, upgrade CS Docker Engine, +and then start DHE again: + +``` + $ sudo bash -c "$(sudo docker run docker/trusted-registry stop)" + $ sudo apt-get update && sudo apt-get dist-upgrade docker-engine-cs + $ sudo bash -c "$(sudo docker run docker/trusted-registry start)" +``` + +## Installing Docker Trusted Registry + +Once the commercially supported Docker Engine is installed, you can install DTR +itself. DTR 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 DTR by running the "docker/trusted-registry" container: + +``` + $ sudo bash -c "$(sudo docker run docker/trusted-registry install)" +``` + +> **Note**: `sudo` is needed for `docker/trusted-registry` 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 DTR'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 docker/trusted-registry install)" +Unable to find image 'docker/trusted-registry:latest' locally +Pulling repository docker/trusted-registry +c46d58daad7d: Pulling image (latest) from docker/trusted-registry +c46d58daad7d: Pulling image (latest) from docker/trusted-registry +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 docker/trusted-registry:latest +Unable to find image 'docker/trusted-registry:1.0.0_8ce62a61e058' locally +Pulling repository docker/trusted-registry +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 docker/trusted-registry: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_trusted_registry_load_balancer with docker daemon unix:///var/run/docker.sock +Starting container docker_trusted_registry_load_balancer with docker daemon unix:///var/run/docker.sock +Bringing up docker_trusted_registry_log_aggregator. +Creating container docker_trusted_registry_log_aggregator with docker daemon unix:///var/run/docker.sock +Starting container docker_trusted_registry_log_aggregator with docker daemon unix:///var/run/docker.sock +$ docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +0168f37b6221 docker/trusted-registry-log-aggregator:1.0.0_8ce62a61e058 "log-aggregator" 4 seconds ago Up 4 seconds docker_trusted_registry_log_aggregator +b51c73bebe8b docker/trusted-registry-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_trusted_registry_load_balancer +e8327864356b docker/trusted-registry-admin-server:1.0.0_8ce62a61e058 "server" 5 seconds ago Up 5 seconds 80/tcp docker_trusted_registry_admin_server +52885a6e830a docker/trusted-registry-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 DTR +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 DTR Domain Name + +The DTR 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 +DTR server. +Hitting the "Save and Restart DTR Server" button will generate a new certificate, which will be used +by both the DTR Administrator web interface and the DTR Registry server. + +After the server restarts, you will again need to allow the connection to the untrusted DTR web admin site. + +![http settings page](../assets/admin-settings-http-unlicensed.png) + +Lastly, you will see a warning notifying you that this instance of DTR is +unlicensed. You'll correct this in the next step. + +### Add your license + +The DTR 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 DTR 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 DTR license](../assets/docker-hub-org-enterprise-license.png) + +3. Next, go to your DTR 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 DTR" button, which will quit DTR 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 DTR + +Securing DTR is **required**. You will not be able to push or pull from DTR until you secure it. + +There are several options and methods for securing DTR. For more information, +see the [configuration documentation](./configuration.md#security) + +### Using DTR to push and pull images + +Now that you have DTR 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 DTR to Push and pull images](./userguide.md#using-dtr-to-push-and-pull-images). + +### DTR web interface and registry authentication + +By default, there is no authentication set on either the DTR web admin +interface or the DTR registry. You can restrict access using an in-DTR +configured set of users (and passwords), or you can configure DTR to use LDAP- +based authentication. + +See [DTR Authentication settings](./configuration.md#authentication) for more +details. + +## Upgrading Docker Trusted Registry + +DTR 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 DTR 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, DTR +will pull new DTR container images from the Docker Hub. If you have not already +connected to Docker Hub, DTR will prompt you to log in. + +The upgrade process requires a small amount of downtime to complete. To complete +the upgrade, DTR will: +* Connect to the Docker Hub to pull new container images with the new version of +DTR. +* 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. + +You should now [upgrade CS Docker Engine](#upgrading-the-commercially-supported-docker-engine). + +> **Note**: If Docker engine is upgraded first (DTR 1.0.0 on CS Docker Engine 1.6.1), +> DTR can still be upgraded from the command line by running: +> +> `sudo bash -c "$(sudo docker run docker/trusted-registry:1.0.0 upgrade 1.0.1)"` + +## Next Steps + +For information on configuring DTR for your environment, take a look at the +[Configuration instructions](./configuration.md). diff --git a/quick-start.md b/quick-start.md new file mode 100644 index 0000000000..7fac776709 --- /dev/null +++ b/quick-start.md @@ -0,0 +1,338 @@ + + + + +# Docker Trusted Registry Quick Start: Basic User Workflow + +## Overview + +This Quick Start Guide will give you a hands-on look at the basics of using +Docker Trusted Registry (DTR), Docker’s on-premise image storage application. +This guide will walk you through using DTR 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 DTR 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 DTR 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 DTR +4. Pulling the customized image from DTR +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 DTR +> reachable at dtr.yourdomain.com. If you need help installing and configuring +> DTR, 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. By default, if +Docker can't find an image locally, it will attempt to pull the image from the +Docker Hub. From the CLI of a machine running the Docker Engine on your network, use +the +[`docker pull`](https://docs.docker.com/reference/commandline/cli/#pull) +command to pull the public Jenkins image. + + $ 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, which lists your available images: + + $ 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 DTR. + +### 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 dtr.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 `dtr.yourdomain.com` registry (your +local DTR instance). This will be important when you need to `push` the +customized image to DTR 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 + dtr.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 Trusted Registry + +> **Note**: If your DTR instance has authentication enabled, you will need to +> use your command line to `docker login ` (e.g., `docker login +> dtr.yourdomain.com`). +> +> Failures due to unauthenticated `docker push` and `docker pull` commands will +> look like : +> +> $ docker pull dtr.yourdomain.com/hello-world +> Pulling repository dtr.yourdomain.com/hello-world +> FATA[0001] Error: image hello-world:latest not found +> +> $ docker push dtr.yourdomain.com/hello-world +> The push refers to a repository [dtr.yourdomain.com/hello-world] (len: 1) +> e45a5af57b00: Image push failed +> FATA[0001] Error pushing to registry: token auth attempt for registry +> https://dtr.yourdomain.com/v2/: +> https://dtr.yourdomain.com/auth/v2/token/ +> ?scope=repository%3Ahello-world%3Apull%2Cpush&service=dtr.yourdomain.com +> request failed with status: 401 Unauthorized + +Now that you’ve created the custom image, it can be pushed to DTR using the +[`docker push`command](https://docs.docker.com/reference/commandline/cli/#push): + + $ docker push dtr.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 DTR: + +![DTR 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 DTR. + +## Pulling from Docker Trusted Registry +To pull the `jnkns-img` image from DTR, run the +[`docker pull`](https://docs.docker.com/reference/commandline/cli/#pull) +command from any Docker Host that has access to your DTR instance: + + $ docker pull dtr.yourdomain.com/ci-infrastructure/jnkns-img + latest: Pulling from dtr.yourdomain.com/ci-infrastructure/jnkns-img + 511136ea3c5a: Pull complete + 848d84b4b2ab: Pull complete + 71d9d77ae89e: Pull complete + + 492ed3875e3e: Pull complete + fc0ab3008d40: Pull complete + dtr.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 dtr.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 DTR: + +![DTR console pull throughput](../assets/console-pull.png) + +Now that the `jnkns-img` image has been pulled locally from DTR, you can view it +in the output of the `docker images` command: + + $ docker images + REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE + dtr.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 DTR, 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 dtr.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 dtr.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 DTR instance, allowing them to access a +configured, secured Jenkins instance that can run on any infrastructure. + +## Next Steps + +For more information on using DTR, take a look at the +[User's Guide](./userguide.md). diff --git a/release-notes.md b/release-notes.md new file mode 100644 index 0000000000..a8aa74a9ab --- /dev/null +++ b/release-notes.md @@ -0,0 +1,247 @@ + + + +# Release Notes + +## Docker Trusted Registry + +### DTR 1.0.1 +(11 May 2015) + +- Addresses compatibility issue with 1.6.1 CS Docker Engine + +### DTR 1.0.0 +(23 Apr 2015) + +- First release + +## Commercially Supported Docker Engine + +### CS Docker Engine 1.6.2-cs5 +(21 May 2015) + +For customers running Docker Engine on [supported versions of RedHat Enterprise +Linux](https://www.docker.com/enterprise/support/) with [SELinux +enabled](https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/ +6/html/Security-Enhanced_Linux/sect-Security-Enhanced_Linux-Working_with_SELinux +-Enabling_and_Disabling_SELinux.html), the `docker build` and `docker run` +commands will not have DNS host name resolution and bind-mounted volumes may +not be accessible. +As a result, customers with SELinux will be unable to use hostname-based network +access in either `docker build` or `docker run`, nor will they be able to +`docker run` containers +that use `--volume` or `-v` bind-mounts (with an incorrect SELinux label) in +their environment. By installing Docker +Engine 1.6.2-cs5, customers can use Docker as intended on RHEL with SELinux enabled. + +For example, you see will failures like: + +``` +[root@dtr ~]# docker -v +Docker version 1.6.0-cs2, build b8dd430 +[root@dtr ~]# ping dtr.home.org.au +PING dtr.home.org.au (10.10.10.104) 56(84) bytes of data. +64 bytes from dtr.home.gateway (10.10.10.104): icmp_seq=1 ttl=64 time=0.663 ms +^C +--- dtr.home.org.au ping statistics --- +2 packets transmitted, 2 received, 0% packet loss, time 1001ms +rtt min/avg/max/mdev = 0.078/0.370/0.663/0.293 ms +[root@dtr ~]# docker run --rm -it debian ping dtr.home.org.au +ping: unknown host +[root@dtr ~]# docker run --rm -it debian cat /etc/resolv.conf +cat: /etc/resolv.conf: Permission denied +[root@dtr ~]# docker run --rm -it debian apt-get update +Err http://httpredir.debian.org jessie InRelease + +Err http://security.debian.org jessie/updates InRelease + +Err http://httpredir.debian.org jessie-updates InRelease + +Err http://security.debian.org jessie/updates Release.gpg + Could not resolve 'security.debian.org' +Err http://httpredir.debian.org jessie Release.gpg + Could not resolve 'httpredir.debian.org' +Err http://httpredir.debian.org jessie-updates Release.gpg + Could not resolve 'httpredir.debian.org' +[output truncated] + +``` + +or when running a `docker build`: + +``` +[root@dtr ~]# docker build . +Sending build context to Docker daemon 11.26 kB +Sending build context to Docker daemon +Step 0 : FROM fedora + ---> e26efd418c48 +Step 1 : RUN yum install httpd + ---> Running in cf274900ea35 + +One of the configured repositories failed (Fedora 21 - x86_64), +and yum doesn't have enough cached data to continue. At this point the only +safe thing yum can do is fail. There are a few ways to work "fix" this: + +[output truncated] +``` + + +**Affected Versions**: All previous versions of Docker Engine when SELinux +is enabled. + +Docker **highly recommends** that all customers running previous versions of +Docker Engine update to this release. + +#### **How to workaround this issue** + +Customers who choose not to install this update have two options. The +first option is to disable SELinux. This is *not recommended* for production +systems where SELinux is typically required. + +The second option is to pass the following parameter in to `docker run`. + + --security-opt=label:type:docker_t + +This parameter cannot be passed to the `docker build` command. + +#### **Upgrade notes** + +When upgrading, make sure you stop DTR first, perform the Engine upgrade, and +then restart DTR. + +If you are running with SELinux enabled, previous Docker Engine releases allowed +you to bind-mount additional volumes or files inside the container as follows: + + $ docker run -it -v /home/user/foo.txt:/foobar.txt:ro + +In the 1.6.2-cs5 release, you must ensure additional bind-mounts have the correct +SELinux context. For example, if you want to mount `foobar.txt` as read-only +into the container, do the following to create and test your bind-mount: + +1. Add the `z` option to the bind mount when you specify `docker run`. + + $ docker run -it -v /home/user/foo.txt:/foobar.txt:ro,z + +2. Exec into your new container. + + For example, if your container is `bashful_curie`, open a shell on the + container: + + $ docker exec -it bashful_curie bash + +3. Use `cat` to check the permissions on the mounted file. + + $ cat /foobar.txt + the contents of foobar appear + + If you see the file's contents, your mount succeeded. If you receive a + `Permission denied` message and/or the `/var/log/audit/audit.log` file on + your Docker host contains an AVC Denial message, the mount did not succeed. + + type=AVC msg=audit(1432145409.197:7570): avc: denied { read } for pid=21167 comm="cat" name="foobar.txt" dev="xvda2" ino=17704136 scontext=system_u:system_r:svirt_lxc_net_t:s0:c909,c965 tcontext=unconfined_u:object_r:user_home_t:s0 tclass=file + + Recheck your command line to make sure you passed in the `z` option. + + +### CS Docker Engine 1.6.2-cs4 +(13 May 2015) + +Fix mount regression for `/sys`. + +### CS Docker Engine 1.6.1-cs3 +(11 May 2015) + +Docker Engine version 1.6.1 has been released to address several vulnerabilities +and is immediately available for all supported platforms. Users are advised to +upgrade existing installations of the Docker Engine and use 1.6.1 for new installations. + +It should be noted that each of the vulnerabilities allowing privilege escalation +may only be exploited by a malicious Dockerfile or image. Users are advised to +run their own images and/or images built by trusted parties, such as those in +the official images library. + +Please send any questions to security@docker.com. + + +#### **[CVE-2015-3629](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-3629) Symlink traversal on container respawn allows local privilege escalation** + +Libcontainer version 1.6.0 introduced changes which facilitated a mount namespace +breakout upon respawn of a container. This allowed malicious images to write +files to the host system and escape containerization. + +Libcontainer and Docker Engine 1.6.1 have been released to address this +vulnerability. Users running untrusted images are encouraged to upgrade Docker Engine. + +Discovered by Tõnis Tiigi. + + +#### **[CVE-2015-3627](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-3627) Insecure opening of file-descriptor 1 leading to privilege escalation** + +The file-descriptor passed by libcontainer to the pid-1 process of a container +has been found to be opened prior to performing the chroot, allowing insecure +open and symlink traversal. This allows malicious container images to trigger +a local privilege escalation. + +Libcontainer and Docker Engine 1.6.1 have been released to address this +vulnerability. Users running untrusted images are encouraged to upgrade +Docker Engine. + +Discovered by Tõnis Tiigi. + +#### **[CVE-2015-3630](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-3630) Read/write proc paths allow host modification & information disclosure** + +Several paths underneath /proc were writable from containers, allowing global +system manipulation and configuration. These paths included `/proc/asound`, +`/proc/timer_stats`, `/proc/latency_stats`, and `/proc/fs`. + +By allowing writes to `/proc/fs`, it has been noted that CIFS volumes could be +forced into a protocol downgrade attack by a root user operating inside of a +container. Machines having loaded the timer_stats module were vulnerable to +having this mechanism enabled and consumed by a container. + +We are releasing Docker Engine 1.6.1 to address this vulnerability. All +versions up to 1.6.1 are believed vulnerable. Users running untrusted +images are encouraged to upgrade. + +Discovered by Eric Windisch of the Docker Security Team. + +#### **[CVE-2015-3631](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-3631) Volume mounts allow LSM profile escalation** + +By allowing volumes to override files of `/proc` within a mount namespace, a user +could specify arbitrary policies for Linux Security Modules, including setting +an unconfined policy underneath AppArmor, or a `docker_t` policy for processes +managed by SELinux. In all versions of Docker up until 1.6.1, it is possible for +malicious images to configure volume mounts such that files of proc may be overridden. + +We are releasing Docker Engine 1.6.1 to address this vulnerability. All versions +up to 1.6.1 are believed vulnerable. Users running untrusted images are encouraged +to upgrade. + +Discovered by Eric Windisch of the Docker Security Team. + +#### **AppArmor policy improvements** + +The 1.6.1 release also marks preventative additions to the AppArmor policy. +Recently, several CVEs against the kernel have been reported whereby mount +namespaces could be circumvented through the use of the sys_mount syscall from +inside of an unprivileged Docker container. In all reported cases, the +AppArmor policy included in libcontainer and shipped with Docker has been +sufficient to deflect these attacks. However, we have deemed it prudent to +proactively tighten the policy further by outright denying the use of the +`sys_mount` syscall. + +Because this addition is preventative, no CVE-ID is requested. + +### CS Docker Engine 1.6.0-cs2 +(23 Apr 2015) + +- First release, please see the [Docker Engine 1.6.0 Release notes](/release-notes/) + for more details. diff --git a/support.md b/support.md new file mode 100644 index 0000000000..cfd641678b --- /dev/null +++ b/support.md @@ -0,0 +1,24 @@ + + + +# Commercial Support Options + +## How to get support + +Purchasing a DTR License or Commercial Support subscription means your questions +and issues about DTR 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/userguide.md b/userguide.md new file mode 100644 index 0000000000..803310c753 --- /dev/null +++ b/userguide.md @@ -0,0 +1,134 @@ + + + + +# Docker Trusted Registry User's Guide + +This guide covers tasks and functions a user of Docker Trusted Registry (DTR) will +need to know about, such as pushing or pulling images, etc. For tasks DTR +administrators need to accomplish, such as configuring or monitoring DTR, please +visit the [Administrator's Guide](./adminguide.md). + +## Overview + +The primary use case for DTR users is to push and pull images to and from the +DTR image storage service. For example, you might pull an Official Image for +Ubuntu from the Docker Hub, customize it with configuration settings for your +infrastructure and then push it to your DTR image storage for other developers +to pull and use for their development environments. + +Pushing and pulling images with DTR works very much like any other Docker +registry: you use the `docker pull` command to retrieve images and the `docker +push` command to add an image to a DTR repository. To learn more about Docker +images, see +[User Guide: Working with Docker Images](https://docs.docker.com/userguide/dockerimages/). For a step-by-step +example of the entire process, see the +[Quick Start: Basic Workflow Guide](./quick-start.md). + +> **Note**: If your DTR instance has authentication enabled, you will need to +>use your command line to `docker login ` (e.g., `docker login +> dtr.yourdomain.com`). +> +> Failures due to unauthenticated `docker push` and `docker pull` commands will +> look like : +> +> $ docker pull dtr.yourdomain.com/hello-world +> Pulling repository dtr.yourdomain.com/hello-world +> FATA[0001] Error: image hello-world:latest not found +> +> $ docker push dtr.yourdomain.com/hello-world +> The push refers to a repository [dtr.yourdomain.com/hello-world] (len: 1) +> e45a5af57b00: Image push failed +> FATA[0001] Error pushing to registry: token auth attempt for registry +> https://dtr.yourdomain.com/v2/: +> https://dtr.yourdomain.com/auth/v2/token/?scope= +> repository%3Ahello-world%3Apull%2Cpush&service=dtr.yourdomain.com +> request failed with status: 401 Unauthorized + +## Pushing Images + +You push an image up to a DTR repository by using the +[`docker push` command](https://docs.docker.com/reference/commandline/cli/#push). + +You can add a `tag` to your image so that you can more easily identify it +amongst other variants and so that it refers to your DTR server. + + `$ docker tag hello-world:latest dtr.yourdomain.com/yourusername/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 your DTR server, `dtr.yourdomain.com`, and the `USERNAME` is +`yourusername`. Lastly, the image tag is set to `hello-mine:latest`. + +Once an image is tagged, you can push it to DTR with: + + `$ docker push dtr.yourdomain.com/demouser/hello-mine:latest` + +> **Note**: If the Docker daemon on which you are running `docker push` doesn't +> have the right certificates set up, you will get an error similar to: +> +> $ docker push dtr.yourdomain.com/demouser/hello-world +> FATA[0000] Error response from daemon: v1 ping attempt failed with error: +> Get https://dtr.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 +> dtr.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/dtr.yourdomain.com/ca.crt + +## Pulling images + +You can retrieve an image with the +[`docker pull` command](https://docs.docker.com/reference/commandline/cli/#run), +or you can retrieve an image and run Docker to build the container with the +[`docker run`command](https://docs.docker.com/reference/commandline/cli/#run). + +To retrieve an image from DTR and then run Docker to build the container, add +the needed info to `docker run`: + + $ docker run dtr.yourdomain.com/yourusername/hello-mine + latest: Pulling from dtr.yourdomain.com/yourusername/hello-mine + 511136ea3c5a: Pull complete + 31cbccb51277: Pull complete + e45a5af57b00: Already exists + Digest: sha256:45f0de377f861694517a1440c74aa32eecc3295ea803261d62f950b1b757bed1 + Status: Downloaded newer image for dtr.yourdomain.com/demouser/hello-mine:latest + +Note that if you don't specify a version, by default the `latest` version of an +image will be pulled. + +If you run `docker images` after this you'll see a `hello-mine` image. + + $ docker images + REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE + dtr.yourdomain.com/yourusername/hello-mine latest e45a5af57b00 3 months ago 910 B + +To pull an image without building the container, use `docker pull` and specify +your DTR registry by adding it to the command: + + $ docker pull dtr.yourdomain.com/yourusername/hello-mine + + +## Next Steps + +For information on administering DTR, take a look at the +[Administrator's Guide](./adminguide.md). + + +