mirror of https://github.com/docker/docs.git
Updating for hugo
Updating the sed tasks Updating image to pull Signed-off-by: Mary Anthony <mary@docker.com>
This commit is contained in:
Mary Anthony
commit
54b3642abb
|
|
@ -0,0 +1,24 @@
|
|||
FROM docs/base:hugo
|
||||
MAINTAINER Mary Anthony <mary@docker.com> (@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 '/^<!.*metadata]>/g' \
|
||||
-e '/^<!.*end-metadata.*>/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' {} \;
|
||||
|
|
@ -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)" .
|
||||
|
|
@ -0,0 +1,112 @@
|
|||
<!--[metadata]>
|
||||
+++
|
||||
title = "Docker Trusted Registry: Admin guide"
|
||||
description = "Documentation describing administration of Docker Trusted Registry"
|
||||
keywords = ["docker, documentation, about, technology, hub, enterprise"]
|
||||
[menu.main]
|
||||
parent="smn_dhe"
|
||||
identifier="smn_dhe_admin"
|
||||
weight=3
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
|
||||
# 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
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
||||
|
||||
|
||||
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 `<component
|
||||
name>-<timestamp at rotation>`, where the "component name" is the service it
|
||||
provides (`manager`, `admin-server`, etc.).
|
||||
|
||||
### Usage statistics and crash reports
|
||||
|
||||
During normal use, 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://<dtr-host-ip>: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).
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 102 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 12 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 18 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 33 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 31 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 34 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 28 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
|
|
@ -0,0 +1,363 @@
|
|||
<!--[metadata]>
|
||||
+++
|
||||
title = "Docker Trusted Registry: Configuration options"
|
||||
description = "Configuration instructions for Docker Trusted Registry"
|
||||
keywords = ["docker, documentation, about, technology, understanding, enterprise, hub, registry"]
|
||||
[menu.main]
|
||||
parent="smn_dhe_admin"
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
|
||||
# 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 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
|
||||
|
||||
|
||||
|
||||
* *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 2>/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 2>/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 2>/dev/null | openssl x509 -outform PEM | sudo tee -a /var/lib/boot2docker/server.pem
|
||||
```
|
||||
|
||||
If your certificate chain is complicated, you may want to use the changes in
|
||||
[Pull request 807](https://github.com/boot2docker/boot2docker/pull/807/files)
|
||||
|
||||
Now you can either reboot your Boot2Docker virtual machine, or run the following to
|
||||
install the server certificate, and then restart the Docker daemon.
|
||||
|
||||
```
|
||||
$ sudo chmod 755 /var/lib/boot2docker/bootsync.sh
|
||||
$ sudo /var/lib/boot2docker/bootsync.sh
|
||||
$ sudo /etc/init.d/docker restart`.
|
||||
```
|
||||
|
||||
### If you can't install the certificates
|
||||
|
||||
If for some reason you can't install the certificate chain on a client Docker host,
|
||||
or your certificates do not have a global CA, you can configure your Docker daemon to run in "insecure" mode. This is done by adding an extra flag,
|
||||
`--insecure-registry host-ip|domain-name`, to your client Docker daemon startup flags.
|
||||
You'll need to restart the Docker daemon for the change to take effect.
|
||||
|
||||
This flag means that the communications between your Docker client and the 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.
|
||||
|
||||
|
||||
|
||||
* *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.
|
||||
|
||||
|
||||
|
||||
* 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 <LDAP Server hostname> -b <User Base DN> -D <Search User DN> -w <Search User Password>
|
||||
```
|
||||
|
||||
or if the LDAP server is set up to allow anonymous access (which means your *Search User DN* and *Search User Password* settings can remain empty):
|
||||
|
||||
```
|
||||
docker run --rm -it svendowideit/ldapsearch -h <LDAP Server hostname> -b <User Base DN> -x
|
||||
```
|
||||
|
||||
The result of these queries should be a (very) long list - if you get an authentication error,
|
||||
then the details you have been given are not sufficient.
|
||||
|
||||
The *User Login Attribute* key setting must match the field used in the LDAP server
|
||||
for the user's login-name. On OpenLDAP, it's generally `uid`, and on Microsoft Active Directory
|
||||
servers, it's `sAMAccountName`. The `ldapsearch` output above should allow you to
|
||||
confirm which setting you need.
|
||||
|
||||
|
||||
|
||||
* *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).
|
||||
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
<!--[metadata]>
|
||||
+++
|
||||
title = "Docker Trusted Registry: Overview"
|
||||
description = "Docker Trusted Registry"
|
||||
keywords = ["docker, documentation, about, technology, understanding, enterprise, hub, registry"]
|
||||
[menu.main]
|
||||
parent="smn_dhe"
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
|
||||
# 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.
|
||||
|
||||
|
|
@ -0,0 +1,366 @@
|
|||
<!--[metadata]>
|
||||
+++
|
||||
title = "Docker Trusted Registry"
|
||||
description = "Installation instructions for Docker Trusted Registry"
|
||||
keywords = ["docker, documentation, about, technology, understanding, enterprise, hub, registry"]
|
||||
[menu.main]
|
||||
parent="mn_install"
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
|
||||
# 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.
|
||||
|
||||
|
||||
|
||||
### 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://<host-ip>/`.
|
||||
|
||||
Your browser will warn you that this is an unsafe site, with a self-signed,
|
||||
untrusted certificate. This is normal and expected; allow this connection
|
||||
temporarily.
|
||||
|
||||
### Setting the 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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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).
|
||||
|
|
@ -0,0 +1,338 @@
|
|||
<!--[metadata]>
|
||||
+++
|
||||
title = "Docker Trusted Registry: Quick-start: Basic Workflow"
|
||||
description = "Brief tutorial on the basics of Docker Trusted Registry user workflow"
|
||||
keywords = ["docker, documentation, about, technology, understanding, enterprise, hub, registry, image, repository"]
|
||||
[menu.main]
|
||||
parent="smn_dhe"
|
||||
weight=1
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
|
||||
|
||||
# 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 <dtr-hostname>` (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
|
||||
<truncated ouput...>
|
||||
492ed3875e3e: Image successfully pushed
|
||||
fc0ab3008d40: Image successfully pushed
|
||||
|
||||
You can view the traffic throughput while the custom image is being pushed from
|
||||
the `System Health` tab in DTR:
|
||||
|
||||
|
||||
|
||||
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
|
||||
<truncated ouput...>
|
||||
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:
|
||||
|
||||
|
||||
|
||||
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
|
||||
<truncated output...>
|
||||
INFO: Jenkins is fully up and running
|
||||
|
||||
> **Note:** The `docker run` command above maps port 1973 in the container
|
||||
> through to port 1973 on the host. This is the HTTPS port you specified in the
|
||||
> Dockerfile earlier. If you specified a different HTTPS port in your
|
||||
> Dockerfile, you will need to substitute this with the correct port numbers for
|
||||
> your environment.
|
||||
|
||||
You can view the newly launched a container, called `jenkins01`, using the
|
||||
[`docker ps` command](https://docs.docker.com/reference/commandline/cli/#ps):
|
||||
|
||||
$ docker ps
|
||||
CONTAINER ID IMAGE COMMAND CREATED STATUS ...PORTS NAMES
|
||||
2e5d2f068504 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://<docker-host>:1973` (Don't forget the `s` at the end of `https`.)
|
||||
|
||||
> **Note:** If you are using a self-signed certificate, you may get a security
|
||||
> warning from your browser telling you that the certificate is self-signed and
|
||||
> not trusted. You may wish to add the certificate to the trusted store in order
|
||||
> to prevent further warnings in the future.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
In another browser session, try to access Jenkins via the default HTTP port 8080
|
||||
`http://<docker-host>:8080`. This should result in a "connection timeout",
|
||||
showing that Jenkins is not available on its default port 8080 over HTTP.
|
||||
|
||||
This demonstration shows your Jenkins image has been configured correctly for
|
||||
HTTPS access, your new plugin was added and is ready for use, and HTTP access
|
||||
has been disabled. At this point, any member of your team can use `docker pull`
|
||||
to access the image from your 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).
|
||||
|
|
@ -0,0 +1,247 @@
|
|||
<!--[metadata]>
|
||||
+++
|
||||
title = "Docker Trusted Registry: Release notes"
|
||||
description = "Release notes for Docker Trusted Registry"
|
||||
keywords = ["docker, documentation, about, technology, understanding, enterprise, hub, registry, release"]
|
||||
[menu.main]
|
||||
parent="smn_release_notes"
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
|
||||
# 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 <imagename>
|
||||
|
||||
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 <imagename>
|
||||
|
||||
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.
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
<!--[metadata]>
|
||||
+++
|
||||
title = "Docker Trusted Registry: Support"
|
||||
description = "Commercial Support"
|
||||
keywords = ["docker, documentation, about, technology, understanding, enterprise, hub, registry, support"]
|
||||
[menu.main]
|
||||
parent="smn_dhe"
|
||||
weight=99
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
|
||||
# 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/)**
|
||||
|
|
@ -0,0 +1,134 @@
|
|||
<!--[metadata]>
|
||||
+++
|
||||
title = "Docker Trusted Registry: User guide"
|
||||
description = "Documentation describing basic use of Docker Trusted Registry"
|
||||
keywords = ["docker, documentation, about, technology, hub, enterprise"]
|
||||
[menu.main]
|
||||
parent="smn_dhe"
|
||||
weight=2
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
|
||||
|
||||
# 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 <dtr-hostname>` (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).
|
||||
|
||||
|
||||
<!--TODO:
|
||||
|
||||
* mention that image aliases that are not in the same repository are not updated - either on push or pull
|
||||
* but that multiple tags in one repo are pushed if you don't specify the `:tag` (ie, `imagename` does not always mean `imagename:latest`)
|
||||
* show what happens for non-latest, and when there are more than one tag in a repo
|
||||
* explain the fully-qualified repo/image name
|
||||
* explain how to remove an image from DTR -->
|
||||
Loading…
Reference in New Issue