diff --git a/datacenter/dtr/2.1/architecture.md b/datacenter/dtr/2.1/architecture.md new file mode 100644 index 0000000000..a612b6b1ff --- /dev/null +++ b/datacenter/dtr/2.1/architecture.md @@ -0,0 +1,93 @@ + + +# DTR architecture + +Docker Trusted Registry (DTR) is a Dockerized application that runs on a Docker +Universal Control Plane cluster. + +![](images/architecture-1.png) + + +## Containers + +When you install DTR on a node, the following containers are started: + +| Name | Description | +|:-------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------| +| dtr-api-<replica_id> | Executes the DTR business logic. It serves the DTR web application, and API | +| dtr-etcd-<replica_id> | A key-value store for persisting DTR configuration settings | +| dtr-jobrunner-<replica_id> | Runs cleanup jobs in the background | +| dtr-nginx-<replica_id> | Receives http and https requests and proxies them to other DTR components. By default it listens to ports 80 and 443 of the host | +| dtr-notary-server-<replica_id> | Receives, validates, and serves content trust metadata, and is consulted when pushing or pulling to DTR with content trust enabled | +| dtr-notary-signer-<replica_id> | Performs server-side timestamp and snapshot signing for content trust metadata | +| dtr-registry-<replica_id> | Implements the functionality for pulling and pushing Docker images. It also handles how images are stored | +| dtr-rethinkdb-<replica_id> | A database for persisting repository metadata | + +All these components are for internal use of DTR. Don't use them in your applications. + +## Networks + +To allow containers to communicate, when installing DTR the following networks +are created: + +| Name | Type | Description | +|:-------|:--------|:---------------------------------------------------------------------------------------| +| dtr-br | bridge | Allows DTR components on the same node to communicate with each other in a secure way | +| dtr-ol | overlay | Allows DTR components running on different nodes to communicate, to replicate DTR data | + + +## Volumes + +DTR uses these named volumes for persisting data: + +| Volume name | Description | +|:--------------------------------|:---------------------------------------------------------------------------------| +| dtr-ca-<replica_id> | Root key material for the DTR root CA that issues certificates | +| dtr-etcd-<replica_id> | DTR configuration data | +| dtr-notary-<replica_id> | Certificate and keys for the Notary components | +| dtr-registry-<replica_id> | Docker images data, if DTR is configured to store images on the local filesystem | +| dtr-rethink-<replica_id> | Repository metadata | + +You can customize the volume driver used for these volumes, by creating the +volumes before installing DTR. During the installation, DTR checks which volumes +don't exist in the node, and creates them using the default volume driver. + +By default, the data for these volumes can be found at +`/var/lib/docker/volumes//_data`. + +## Image storage + +By default, Docker Trusted Registry stores images on the filesystem of the node +where it is running. + +You can also configure DTR to use these storage backends: + +* NFS +* Amazon S3 +* Cleversafe +* OpenStack Swift +* Microsoft Azure + +For highly available installations, you should use a cloud storage system +instead of an NFS mount, since they usually have better performance. + +## High-availability support + +For load balancing and high-availability, you can install multiple replicas of +DTR, and join them to create a cluster. +[Learn more about high availability](high-availability/index.md). + +## Where to go next + +* [System requirements](install/system-requirements.md) +* [Install DTR](install/index.md) diff --git a/datacenter/dtr/2.1/assets/gc1.png b/datacenter/dtr/2.1/assets/gc1.png new file mode 100644 index 0000000000..2db3446ceb Binary files /dev/null and b/datacenter/dtr/2.1/assets/gc1.png differ diff --git a/datacenter/dtr/2.1/assets/gc3.png b/datacenter/dtr/2.1/assets/gc3.png new file mode 100644 index 0000000000..1832e7f667 Binary files /dev/null and b/datacenter/dtr/2.1/assets/gc3.png differ diff --git a/datacenter/dtr/2.1/assets/repo.png b/datacenter/dtr/2.1/assets/repo.png new file mode 100644 index 0000000000..9b08a6bbfc Binary files /dev/null and b/datacenter/dtr/2.1/assets/repo.png differ diff --git a/datacenter/dtr/2.1/configure/config-general.md b/datacenter/dtr/2.1/configure/config-general.md new file mode 100644 index 0000000000..4295830cac --- /dev/null +++ b/datacenter/dtr/2.1/configure/config-general.md @@ -0,0 +1,53 @@ ++++ +title = "Configure general settings" +description = "Configure general settings for Docker Trusted Registry" +keywords = ["docker, documentation, about, technology, understanding, enterprise, hub, general, domain name, HTTP, HTTPS ports, registry"] +[menu.main] +parent="workw_dtr_configure" +identifier="dtr_configure_general" +weight=3 ++++ + +# Configure general settings + +This document describes the general settings you need to configure. + +## Configure your domain name and port settings + +Each setting on this page is explained in the Docker Trusted Registry UI. + +* *Domain Name*: **required**. By default it is an empty string. It is the fully qualified domain name assigned to the Docker Trusted Registry host. +* *HTTP Port*: defaults to 80 and is used as the entry point for the image storage service. To see load balancer status, you can query +http://<dtr-host>/load_balancer_status. +* *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. +* *Upgrade checking*: enables or disables automatic checking for the Trusted Registry software updates. + +If you need the Trusted Registry to re-generate a self-signed certificate at +some point, you can change the domain name. Whenever the domain name does not +match the current certificate, a new self-signed certificate is generated +for the new domain. This also works with IP addresses. + + +## Docker Content Trust + +The Trusted Registry integrates with Docker Notary by default to provide +Content Trust functionality, allowing your organization to push and pull +trusted images. After pushing images in the Trusted Registry, you can see +which image tags were signed by viewing the appropriate repositories through +Trusted Registry's web interface. + +To configure your Docker client to be able to push signed images to Docker +Trusted Registry, refer to the CLI Reference's [Environment Variables +Section](/engine/reference/commandline/cli.md#environment-variables) and +[Notary Section](/engine/reference/commandline/cli.md#notary). + +This requires you to set the `DOCKER_CONTENT_TRUST` variable and configure +your system to trust Docker Trusted Registry's TLS certificate if it doesn't +already. + +## See also + +* [Configure storage settings](config-storage.md) diff --git a/datacenter/dtr/2.1/configure/config-security.md b/datacenter/dtr/2.1/configure/config-security.md new file mode 100644 index 0000000000..81f07be162 --- /dev/null +++ b/datacenter/dtr/2.1/configure/config-security.md @@ -0,0 +1,228 @@ ++++ +title = "Security configuration" +description = "Security configuration for Docker Trusted Registry" +keywords = ["docker, documentation, about, technology, understanding, configuration, security, enterprise, hub, registry"] +[menu.main] +parent="workw_dtr_configure" +identifier="dtr_configure_security" +weight=4 ++++ + +# Security configuration + +This document describes the security settings you need to configure. + +* *SSL Certificate*: Used to enter the hash (string) from the SSL Certificate. +This cert must be accompanied by its private key, entered below. +* *SSL Private Key*: The hash from the private key associated with the provided +SSL Certificate (as a standard x509 key pair). + +In order to run, the Trusted Registry requires encrypted communications through HTTPS/SSL between (a) the Trusted Registry and your Docker Engine(s), and (b) between your web browser and the Trusted Registry admin server. There are a few options for setting this up: + +1. You can use the self-signed certificate Docker Trusted Registry 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 Docker Trusted Registry](#adding-your-own-registry-certificates-to-dtr). + +However, if you choose to use the Trusted Registry-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](#installing-registry-certificates-on-client-docker-daemons) a registry certificate on all of your client Docker daemons, or + +* Set your [client Docker daemons](#if-you-can-t-install-the-certificates) to run with an unconfirmed connection to the registry. + +### Generate 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 Docker Trusted +Registry, and install it onto the client Docker daemon hosts as seen in the +following section. + + +### Add your own registry certificates + +Whichever method you use to generate certificates, once you have them you can +set up your Trusted Registry server to use them. + +1. Navigate to Settings > Security, and put 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. + +2. Click Save, and then wait for the Trusted Registry Admin site to restart +and reload. It should now be using the new certificate. Once the Security page has reloaded, it displays `#` hashes instead of the +certificate text you pasted. + +If your certificate is signed by a chain of Certificate Authorities that are +already trusted by your Docker daemon servers, you can skip the following +"Install registry certificates" step. + + +### Install 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 Trusted Registry certificates on each +Linux distribution has slightly different steps. + +You can test this certificate using `curl`: + +``` +$ curl https://dtr.yourdomain.com/v2/ +curl: (60) SSL certificate problem: self signed certificate +``` + +For details see: 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. For example, 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. Run the following commands on the Trusted Registry host. + +#### 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/Centos + +``` + $ 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 +``` + +#### Docker Machine and Boot2Docker + +You'll need to make some persistent changes using `bootsync.sh` in your +Boot2Docker-based virtual machine (as documented in [local customization](https://github.com/boot2docker/boot2docker/blob/master/doc/FAQ.md#local-customisation-with-persistent-partition)). To do this: + +1. `docker-machine ssh dev` to enter the VM +2. `vi /var/lib/boot2docker/bootsync.sh` creates it if it doesn't exist, or edit it if it does. +3. Install the CA cert (or the auto-generated cert) by adding the following code to your `/var/lib/boot2docker/bootsync.sh`: + + ``` + #!/bin/sh + + cat /var/lib/boot2docker/server.pem >> /etc/ssl/certs/ca-certificates.crt + ``` + +4. Next get the certificate from the new Docker Trusted Registry 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 can use the changes in [Pull request 807](https://github.com/boot2docker/boot2docker/pull/807/files) + +5. Either reboot your virtual machine, or run the following commands to +install the server certificate. 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 Trusted Registry server are still encrypted, but the client Docker daemon is not +confirming that the Registry connection is not being hijacked or diverted. + +If you enter a "Domain Name" into the Security settings, it needs to be DNS +resolvable on any client daemons that are running in `insecure-registry` +mode. + +To set the flag, perform the following directions for your operating system. + +#### Ubuntu + +On Ubuntu 14.04 LTS, 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/Centos + +On RHEL/Centos, 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`. + +### Docker Machine and Boot2Docker + +In your Boot2Docker-based virtual machine, 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`. + + +## See also + +* [Configure storage options](config-storage.md) diff --git a/datacenter/dtr/2.1/configure/config-storage.md b/datacenter/dtr/2.1/configure/config-storage.md new file mode 100644 index 0000000000..7c8271af9d --- /dev/null +++ b/datacenter/dtr/2.1/configure/config-storage.md @@ -0,0 +1,217 @@ ++++ +title = "Storage configuration" +description = "Storage configuration for Docker Trusted Registry" +keywords = ["docker, documentation, about, technology, understanding, configuration, storage, storage drivers, Azure, S3, Swift, enterprise, hub, registry"] +[menu.main] +parent="workw_dtr_configure" +identifier="dtr_configure_storage" +weight=5 ++++ + +# Storage configuration + +After installing Docker Trusted Registry, one of your first tasks is to +designate and configure the Trusted Registry storage backend. This document provides the following: + +* Information describing your storage backend options. +* Configuration steps using either the Trusted Registry UI or a YAML file. + +While there is a default storage backend, `filesystem`, the Trusted Registry offers other options that are cloud-based. This flexibility to configure to a different storage backend allows you to: + +* Scale your Trusted Registry +* Leverage storage redundancy +* Store your images anywhere in the cloud +* Take advantage of other features that are critical to your organization + +At first, you might have explored Docker Trusted Registry and Docker Engine by + [installing](../install/index.md) +them on your system in order to familiarize yourself with them. +However, for various reasons such as deployment purposes or continuous +integration, it makes sense to think about your long term organization’s needs +when selecting a storage backend. The Trusted Registry natively supports TLS and +basic authentication. It also ships with a [notification system](/registry/notifications.md), calling webhooks in response to activity. The notification system also provides both extensive logging and +reporting, which is useful for organizations that want to collect metrics. + +## Understand the Trusted Registry storage backend + +By default, your Trusted Registry data resides as a data volume on the host +`filesystem`. This is where your repositories and images are stored. This +storage driver is the local posix `filesystem` and is configured to use a +directory tree in the local filesystem. It's suitable for development or small +deployments. The `filesystem` can be located on the same computer as the Trusted Registry, or on a separate system. + +Additionally, the Trusted Registry supports these cloud-based storage drivers: + +* Amazon Simple Storage Solution **S3** +* OpenStack **Swift** +* Microsoft **Azure** Blob Storage + + + +### Filesystem + +If you select `filesystem`, then the Trusted Registry uses the local disk to +store registry files. This backend has a single, required `rootdirectory` +parameter which specifies a subdirectory of `/var/local/dtr/imagestorage` in +which all registry files are stored. The default value of `/local` means the +files are stored in `/var/local/dtr/image-storage/local`. + +The Trusted Registry stores all its data at this location, so ensure there is +adequate space available. To do so, you can run the following commands: + +* To analyze the disk usage: `docker exec -it bash` then run `df -h`. +* To see the file size of your containers, use the `-s` argument of `docker ps -s`. + +### Amazon S3 + +S3 stores data as objects within “buckets” where you read, write, and delete +objects in that container. It too, has a `rootdirectory` parameter. If you select this option, there will be some tasks that you need to first perform [on AWS](https://aws.amazon.com/s3/getting-started/). + +1. You must create an S3 bucket, and write down its name and the AWS zone it +runs on. +2. Determine write permissions for your bucket. +3. S3 flavor comes with DEBUG=false by default. If you need to debug, then you need to add `-e DEBUG=True`. +4. Specify an AWS region, which is dependent on your S3 location, for example, use `-e AWS_REGION=”eu-west-1”`. +5. Ensure your host time is correct. If your host clock is still running on the main computer, but not on the docker host virtual machine, then you will have +time differences. This may cause an issue if you try to authenticate with Amazon +web services. +6. You will also need your AWS access key and secret key. Learn [more about it ](http://docs.aws.amazon.com/general/latest/gr/managing-aws-access-keys.html) here. + +Conversely, you can further limit what users access in the Trusted Registry when you use AW to host your Trusted Registry. Instead of using the UI to enter information, you can create an [IAM user policy](http://docs.aws.amazon.com/AmazonS3/latest/dev/example-policies-s3.html) which is a JSON description of the effects, actions, and resources available to +a user. The advantage of using this method instead of configuring through the Trusted Registry UI is that you can restrict what users can access. You apply the policy as part of the process of installing the Trusted Registry on AW. To set a policy through the AWS command line, save the policy into a file, +for example `TrustedRegistryUserPerms.json`, and pass it to the +put-user-policy AWS command: + +``` +$ aws iam put-user-policy --user-name MyUser --policy-name TrustedRegistryUserPerms --policy-document file://C:\Temp\TrustedRegistryUserPerms.json +``` + +You can also set a policy through your AWS console. For more information about +setting IAM policies using the command line or the console, review the AWS +[Overview of IAM Policies](http://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) article or visit the console Policies page. + +The following example describes the minimum permissions set which allows +Trusted Registry users to access, push, pull, and delete images. + +``` +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "s3:ListAllMyBuckets", + "Resource": "arn:aws:s3:::*" + }, + { + "Effect": "Allow", + "Action": [ + "s3:ListBucket", + "s3:GetBucketLocation" + ], + "Resource": "arn:aws:s3:::" + }, + { + "Effect": "Allow", + "Action": [ + "s3:PutObject", + "s3:GetObject", + "s3:DeleteObject" + ], + "Resource": "arn:aws:s3:::/*" + } + ] +} + +``` + +### OpenStack Swift + +OpenStack Swift, also known as OpenStack Object Storage, is an open source +object storage system that is licensed under the Apache 2.0 license. Refer to [Swift documentation](http://docs.openstack.org/developer/swift/) to get started. + + + +### Microsoft Azure + +This storage backend uses Microsoft’s Azure Blob storage. Data is stored within +a paid Windows Azure storage account. Refer to Microsoft's Azure +[documentation](https://azure.microsoft.com/en-us/services/storage/) which +explains how to set up your Storage account. + +## Configure your Trusted Registry storage backend + +Once you select your driver, you need to configure it through the UI or use a +YAML file (which is discussed further in this document.) + +1. From the main Trusted Registry screen, navigate to Settings > Storage. +2. Under Storage Backend, use the drop down menu to select your storage. The screen refreshes to reflect your option. +3. Enter your configuration settings. If you're not sure what a particular parameter does, then find your driver from the following headings so that you can see a detailed explanation. +4. Click Save. The Trusted Registry restarts so that your changes take effect. + +>**Note**: Changing your storage backend requires you to restart the Trusted Registry. + +See the [Registry configuration](/registry/configuration.md) +documentation for the full options specific to each driver. Storage drivers can +be customized through the [Docker Registry storage driver +API](/registry/storage-drivers/index.md#storage-driver-api). + + +### Filesystem settings + +The [filesystem storage backend](/registry/configuration.md#filesystem) +has only one setting, the "Storage directory". + +### S3 settings + +If you select the [S3 storage backend](/registry/configuration.md#s3), then you +need to set "AWS region", "Bucket name", "Access Key", and "Secret Key". + +### Azure settings + +Set the "Account name", "Account key", "Container", and "Realm" on the [Azure storage backend](/registry/configuration.md#azure) page. + +### Openstack Swift settings + +View the [Openstack Swift settings](/registry/configuration.md#openstack-swift) +documentation so that you can set up your storage settings: authurl, username, +password, container, tenant, tenantid, domain, domainid, insecureskipverify, +region, chunksize, and prefix. + +## Configure using a YAML file + +If the previous quick setup options are not sufficient to configure your +Registry options, you can upload a YAML file. The schema of this file is +identical to that used by the [Registry](/registry/configuration.md). + +There are several benefits to using a YAML file as it can provide an +additional level of granularity in defining your storage backend. Advantages +include: + +* Overriding specific configuration options. +* Overriding the entire configuration file. +* Selecting from the entire list of configuration options. + +**To configure**: + +1. Navigate to the Trusted Registry UI > Settings > Storage. +2. Select Download to get the text based file. It contains a minimum amount +of information and you're going to need additional data based on your driver and +business requirements. +3. Go [here](/registry/configuration.md#list-of-configuration-options") to see the open source YAML file. Copy the sections you need and paste into your `storage.yml` file. Note that some settings may contradict others, so +ensure your choices make sense. +4. Save the YAML file and return to the UI. +5. On the Storage screen, upload the file, review your changes, and click Save. + +## See also + +* [Configure security settings](config-security.md) diff --git a/datacenter/dtr/2.1/configure/configuration.md b/datacenter/dtr/2.1/configure/configuration.md new file mode 100644 index 0000000000..56619993ad --- /dev/null +++ b/datacenter/dtr/2.1/configure/configuration.md @@ -0,0 +1,43 @@ ++++ +title = "Configuration overview" +description = "Configuration overview for Docker Trusted Registry" +keywords = ["docker, documentation, about, technology, understanding, enterprise, hub, registry"] +[menu.main] +parent="workw_dtr_configure" +identifier="dtr_configuration" +weight=2 ++++ + +# Configure overview + +When you first install Docker Trusted Registry, you need to configure it. Use +this overview to see what you can configure. + +To start, navigate to the Trusted Registry user interface (UI) > Settings, to +view configuration options. Configuring is grouped by the following: + +* [General settings](config-general.md) (ports, proxies) +* [Security settings](config-security.md) +* [Storage settings](config-storage.md) +* [License](../install/license.md) +* Updates + + +Saving changes you've made to settings will restart various services, as follows: + + * General settings: full Docker Trusted Registry restart + * License change: full Docker Trusted Registry restart + * SSL change: Nginx reload + * Storage config: only registries restart + +## Docker daemon logs + +Both the Trusted Registry and the Docker daemon collect and store log messages. To limit duplication of the Docker daemon logs, add the following parameters in a Trusted Registry CLI to the Docker daemon and then restart the daemon. + +`docker daemon --log-opt max-size 100m max-file=1` + + +## See also + +* [Monitor DTR](../monitor-troubleshoot/index.md) +* [Troubleshoot DTR](../monitor-troubleshoot/troubleshoot.md) diff --git a/datacenter/dtr/2.1/configure/index.md b/datacenter/dtr/2.1/configure/index.md new file mode 100644 index 0000000000..6dc309ca76 --- /dev/null +++ b/datacenter/dtr/2.1/configure/index.md @@ -0,0 +1,20 @@ + + +# Configure DTR + +This section includes the following topics: + +* [Configuration overview](configuration.md) +* [Configure general settings](config-general.md) +* [Security configuration](config-security.md) +* [Storage configuration](config-storage.md) diff --git a/datacenter/dtr/2.1/configure/use-your-certificates.md b/datacenter/dtr/2.1/configure/use-your-certificates.md new file mode 100644 index 0000000000..6b15a47dc6 --- /dev/null +++ b/datacenter/dtr/2.1/configure/use-your-certificates.md @@ -0,0 +1,51 @@ ++++ +title = "Use your own certificates" +description = "Learn how to configure Docker Trusted Registry to use your own certificates" +keywords = ["Universal Control Plane, UCP, certificate, authentiation, tls"] +[menu.main] +parent="workw_dtr_configure" +identifier="dtr-configure-certs" +weight=0 ++++ + +# Use your own certificates + +By default the DTR services are exposed using HTTPS, to ensure all +communications between clients and DTR is encrypted. Since DTR +replicas use self-signed certificates for this, when a client accesses +DTR, their browsers won't trust this certificate, so the browser displays a +warning message. + +You can configure DTR to use your own certificates, so that it is automatically +trusted by your users' browser and client tools. + +## Replace the server certificates + +To configure DTR to use your own certificates and keys, go to the +**DTR web UI**, navigate to the **Settings** page, and scroll down to the +**Domain** section. + +![](../images/use-your-certificates-1.png) + + +Set the DTR domain name and upload the certificates and key: + +* Load balancer/public address, is the domain name clients will use to access DTR. +* TLS certificate, is the server certificate and any intermediate CA public +certificates. This certificate needs to be valid for the DTR public address, +and have SANs for all addresses used to reach the DTR replicas, including load +balancers. +* TLS private key is the server private key. +* TLS CA is the root CA public certificate. + +Finally, click **Save** for the changes to take effect. + +If you're using certificates issued by a globally trusted certificate authority, +any web browser or client tool should now trust DTR. If you're using an internal +certificate authority, you'll need to [configure your system to trust that +certificate authority](../repos-and-images/index.md). + +## Where to go next + +* [Configure your Docker Engine](../repos-and-images/index.md) +* [Pull an image](../repos-and-images/pull-an-image.md) diff --git a/datacenter/dtr/2.1/high-availability/backups-and-disaster-recovery.md b/datacenter/dtr/2.1/high-availability/backups-and-disaster-recovery.md new file mode 100644 index 0000000000..764bc8d8e6 --- /dev/null +++ b/datacenter/dtr/2.1/high-availability/backups-and-disaster-recovery.md @@ -0,0 +1,138 @@ + + + +# Backups and disaster recovery + +When you decide to start using Docker Trusted Registry on a production +setting, you should [configure it for high availability](index.md). + +The next step is creating a backup policy and disaster recovery plan. + +## DTR data persistency + +Docker Trusted Registry persists: + +* Configurations: the cluster configurations are stored on a key-value store +that is replicated through all DTR replicas. +* Repository metadata: the information about the repositories and +images deployed. This information is replicated through all DTR replicas. +* Certificates and keys: the certificates, public keys, and private keys that +are used for mutual TLS communication. + +This data is persisted on the host where DTR is running, using named volumes. +[Learn more about DTR named volumes](../architecture.md). + +DTR also persists Docker images on the filesystem of the host running DTR, or +on a cloud provider, depending on the way DTR is configured. + +## Backup DTR data + +To perform a backup of a DTR node, use the `backup` command. This +command creates a backup of DTR: + +* Configurations, +* Repository metadata, +* Certificates and keys used by DTR. + +These files are added to a tar archive, and the result is streamed to stdout. + +The backup command does not create a backup of Docker images. You should +implement a separate backup policy for the Docker images, taking in +consideration whether your DTR installation is configured to store images on the +filesystem or using a cloud provider. + +The backup command also doesn't create a backup of the users and organizations. +That data is managed by UCP, so when you create a UCP backup you're creating +a backup of the users and organizations metadata. + +When creating a backup, the resulting .tar file contains sensitive information +like private keys. You should ensure the backups are stored securely. + +You can check the +[reference documentation](../reference/backup.md), for the +backup command to learn about all the available flags. + +As an example, to create a backup of a DTR node, you can use: + +```bash +# Create the backup +$ docker run -i --rm docker/dtr:2.1.0-beta3 backup \ + --ucp-url \ + --ucp-insecure-tls \ + --existing-replica-id \ + --ucp-username \ + --ucp-password > /tmp/backup.tar +``` + +Where: + +* `--ucp-url` is the address of UCP, +* `--ucp-insecure-tls` is to trust the UCP TLS certificate, +* `--existing-replica-id` is the id of the replica to backup, +* `--ucp-username`, and `--ucp-password` are the credentials of a UCP administrator. + +To validate that the backup was correctly performed, you can print the contents +of the tar file created: + +```bash +$ tar -tf /tmp/backup.tar +``` + +## Restore DTR data + +You can restore a DTR node from a backup using the `restore` +command. +This command performs a fresh installation of DTR, and reconfigures it with +the configuration created during a backup. + +The command starts by installing DTR, restores the configurations stored on +etcd, and then restores the repository metadata stored on RethinkDB. You +can use the `--config-only` option, to only restore the configurations stored +on etcd. + +This command does not restore Docker images. You should implement a separate +restore procedure for the Docker images stored in your registry, taking in +consideration whether your DTR installation is configured to store images on +the filesystem or using a cloud provider. + +You can check the +[reference documentation](../reference/backup.md), for the +backup command to learn about all the available flags. + + +As an example, to install DTR on the host and restore its +state from an existing backup: + +```bash +# Install and restore configurations from an existing backup +$ docker run -i --rm \ + docker/dtr:2.1.0-beta3 restore \ + --ucp-url \ + --ucp-insecure-tls \ + --ucp-username \ + --ucp-password \ + --dtr-load-balancer < /tmp/backup.tar +``` + +Where: + +* `--ucp-url` is the address of UCP, +* `--ucp-insecure-tls` is to trust the UCP TLS certificate, +* `--ucp-username`, and `--ucp-password` are the credentials of a UCP administrator, +* `--dtr-load-balancer` is the domain name or ip where DTR can be reached. + + +## Where to go next + +* [Set up high availability](index.md) +* [DTR architecture](../architecture.md) diff --git a/datacenter/dtr/2.1/high-availability/index.md b/datacenter/dtr/2.1/high-availability/index.md new file mode 100644 index 0000000000..8e9d719486 --- /dev/null +++ b/datacenter/dtr/2.1/high-availability/index.md @@ -0,0 +1,92 @@ + + +# Set up high availability + +Docker Trusted Registry (DTR) is designed for high availability. + +When you first install DTR, you create a cluster with a single DTR replica. +Replicas are single instances of DTR that can be joined together to form a +cluster. +When joining new replicas to the cluster, you'll be creating new DTR instances +that are running the same set of services. Any change to the state of an +instance is replicated across all other instances. + +![](../images/high-availability-1.png) + +Having a DTR cluster with multiple replicas, allows you to: + +* Load-balance user requests across the DTR replicas, +* Keep the DTR cluster working if a replica fails. + +To make a DTR installation tolerant to failures, add additional replicas to +the DTR cluster. + +| DTR replicas | Failures tolerated | +|:------------:|:------------------:| +| 1 | 0 | +| 3 | 1 | +| 5 | 2 | +| 7 | 3 | + + +When sizing your DTR installation for high-availability, +follow these rules of thumb: + +* Don't create a DTR cluster with just two replicas. Your cluster +won't tolerate any failures, and it's possible that you experience performance +degradation. +* When a replica fails, the number of failures tolerated by your cluster +decreases. Don't leave that replica offline for long. +* Adding too many replicas to the cluster might also lead to performance +degradation, as data needs to be replicated across all replicas. + +## Size your cluster + +When installing DTR for production, you should have dedicated nodes for running: + +* Docker Universal Control Plane (UCP) controller nodes, +* DTR replicas, +* Your own applications. + +Having dedicated nodes ensures all applications will remain performant since +they have dedicated resources for them. +It also makes it easier to implement backup policies and disaster recovery +plans for UCP and DTR. + +To have have high-availability on UCP and DTR, you need a minimum of: + +* 3 dedicated nodes to install UCP with high availability, +* 3 dedicated nodes to install DTR with high availability, +* As many nodes as you want for running your containers and applications. + + +![](../images/high-availability-2.png) + +## Load balancing + +DTR does not provide a load balancing service. You can use use an on-premises +or cloud-based load balancer to balance requests across multiple DTR replicas. + +Make sure you configure your load balancer to: + +* Load-balance TCP traffic on ports 80 and 443, +* Not terminate HTTPS connections, +* Use the `/load_balancer_status` endpoint on each DTR replica, to check if +the replica is healthy and if it should remain on the load balancing pool or +not. + +## Where to go next + +* [Backups and disaster recovery](backups-and-disaster-recovery.md) +* [DTR architecture](../architecture.md) diff --git a/datacenter/dtr/2.1/high-availability/menu.md b/datacenter/dtr/2.1/high-availability/menu.md new file mode 100644 index 0000000000..87031dacfd --- /dev/null +++ b/datacenter/dtr/2.1/high-availability/menu.md @@ -0,0 +1,12 @@ + diff --git a/datacenter/dtr/2.1/images/Makefile b/datacenter/dtr/2.1/images/Makefile new file mode 100644 index 0000000000..15b73ad543 --- /dev/null +++ b/datacenter/dtr/2.1/images/Makefile @@ -0,0 +1,47 @@ + +SIZE="1280px" +HOST=dtr.domain.com +HOSTIP:=192.168.18.131 +HOSTURL=https://$(HOST) +IMAGE=svendowideit/screenshot +#IMAGE=screenshot +RUNOPTS=docker run --rm -v $(CURDIR):/srv --add-host $(HOST):$(HOSTIP) +RUN=$(RUNOPTS) $(IMAGE) + +all: + # Needs to be run with no authentication + $(RUN) $(HOSTURL)/admin/ admin-metrics.png $(SIZE) + $(RUN) $(HOSTURL)/admin/logs/ admin-logs.png $(SIZE) + $(RUN) $(HOSTURL)/admin/settings/auth/ admin-settings-authentication.png $(SIZE) + $(RUN) $(HOSTURL)/admin/settings/general admin-settings.png $(SIZE) + $(RUN) $(HOSTURL)/admin/settings/security admin-settings-security.png $(SIZE) + $(RUN) $(HOSTURL)/admin/settings/storage admin-settings-storage.png $(SIZE) + $(RUN) $(HOSTURL)/admin/settings/license admin-settings-license.png $(SIZE) + +manual: + # --env-file=passwords.env + $(RUNOPTS) --env-file=passwords.env \ + $(IMAGE) \ + $(HOSTURL)/admin/settings#auth admin-settings-authentication-basic.png $(SIZE) + + #admin-settings-authentication-ldap.png + + +# TODO: needs manual intervention atm +qs1: + # this requires the hostname to resolve. + echo "$HOST $HOSTIP" >> /etc/hosts + # and requires that host to be added to the docker daemon's insecure registry settings + # maybe use a dind daemon? + + docker pull jenkins + docker tag -f jenkins t400s.home.org.au/ci-infrastructure/jnkns-img + docker push t400s.home.org.au/ci-infrastructure/jnkns-img + sleep 1 + $(RUN) $(HOSTURL)/admin/ console-push.png $(SIZE) + sleep 10 +qs2: + docker rmi jenkins t400s.home.org.au/ci-infrastructure/jnkns-img + docker pull t400s.home.org.au/ci-infrastructure/jnkns-img + sleep 1 + $(RUN) $(HOSTURL)/admin/ console-pull.png $(SIZE) diff --git a/datacenter/dtr/2.1/images/admin-logs.png b/datacenter/dtr/2.1/images/admin-logs.png new file mode 100644 index 0000000000..de2920f3ba Binary files /dev/null and b/datacenter/dtr/2.1/images/admin-logs.png differ diff --git a/datacenter/dtr/2.1/images/admin-metrics.png b/datacenter/dtr/2.1/images/admin-metrics.png new file mode 100644 index 0000000000..99a5d548ac Binary files /dev/null and b/datacenter/dtr/2.1/images/admin-metrics.png differ diff --git a/datacenter/dtr/2.1/images/admin-settings-auth.png b/datacenter/dtr/2.1/images/admin-settings-auth.png new file mode 100644 index 0000000000..d7dd0bef85 Binary files /dev/null and b/datacenter/dtr/2.1/images/admin-settings-auth.png differ diff --git a/datacenter/dtr/2.1/images/admin-settings-authentication-basic.png b/datacenter/dtr/2.1/images/admin-settings-authentication-basic.png new file mode 100644 index 0000000000..3d9cbbe463 Binary files /dev/null and b/datacenter/dtr/2.1/images/admin-settings-authentication-basic.png differ diff --git a/datacenter/dtr/2.1/images/admin-settings-authentication-ldap.png b/datacenter/dtr/2.1/images/admin-settings-authentication-ldap.png new file mode 100644 index 0000000000..22b2b13598 Binary files /dev/null and b/datacenter/dtr/2.1/images/admin-settings-authentication-ldap.png differ diff --git a/datacenter/dtr/2.1/images/admin-settings-authentication.png b/datacenter/dtr/2.1/images/admin-settings-authentication.png new file mode 100644 index 0000000000..6453784c17 Binary files /dev/null and b/datacenter/dtr/2.1/images/admin-settings-authentication.png differ diff --git a/datacenter/dtr/2.1/images/admin-settings-license.png b/datacenter/dtr/2.1/images/admin-settings-license.png new file mode 100644 index 0000000000..5ed5559032 Binary files /dev/null and b/datacenter/dtr/2.1/images/admin-settings-license.png differ diff --git a/datacenter/dtr/2.1/images/admin-settings-license2.png b/datacenter/dtr/2.1/images/admin-settings-license2.png new file mode 100644 index 0000000000..725ddd9281 Binary files /dev/null and b/datacenter/dtr/2.1/images/admin-settings-license2.png differ diff --git a/datacenter/dtr/2.1/images/admin-settings-security.png b/datacenter/dtr/2.1/images/admin-settings-security.png new file mode 100644 index 0000000000..67077fdf2d Binary files /dev/null and b/datacenter/dtr/2.1/images/admin-settings-security.png differ diff --git a/datacenter/dtr/2.1/images/admin-settings-storage-azure.png b/datacenter/dtr/2.1/images/admin-settings-storage-azure.png new file mode 100644 index 0000000000..95c04cc303 Binary files /dev/null and b/datacenter/dtr/2.1/images/admin-settings-storage-azure.png differ diff --git a/datacenter/dtr/2.1/images/admin-settings-storage-s3.png b/datacenter/dtr/2.1/images/admin-settings-storage-s3.png new file mode 100644 index 0000000000..9e142fb309 Binary files /dev/null and b/datacenter/dtr/2.1/images/admin-settings-storage-s3.png differ diff --git a/datacenter/dtr/2.1/images/admin-settings-storage.png b/datacenter/dtr/2.1/images/admin-settings-storage.png new file mode 100644 index 0000000000..f6256d4f77 Binary files /dev/null and b/datacenter/dtr/2.1/images/admin-settings-storage.png differ diff --git a/datacenter/dtr/2.1/images/admin-settings.png b/datacenter/dtr/2.1/images/admin-settings.png new file mode 100644 index 0000000000..665255fb13 Binary files /dev/null and b/datacenter/dtr/2.1/images/admin-settings.png differ diff --git a/datacenter/dtr/2.1/images/architecture-1.png b/datacenter/dtr/2.1/images/architecture-1.png new file mode 100644 index 0000000000..1528ddecf1 Binary files /dev/null and b/datacenter/dtr/2.1/images/architecture-1.png differ diff --git a/datacenter/dtr/2.1/images/authentication-authorization-1.svg b/datacenter/dtr/2.1/images/authentication-authorization-1.svg new file mode 100644 index 0000000000..72b3492d96 --- /dev/null +++ b/datacenter/dtr/2.1/images/authentication-authorization-1.svg @@ -0,0 +1,90 @@ + + + + dtr-authorization-1 + Created with Sketch. + + + + + + + + + + + + + + + billing team + + + + + blog team + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + whale/node + + + + + + whale/java + + + + + + whale/golang + + + + + + + Whale organization + + + + + \ No newline at end of file diff --git a/datacenter/dtr/2.1/images/aws-dtr-sg-rules.png b/datacenter/dtr/2.1/images/aws-dtr-sg-rules.png new file mode 100644 index 0000000000..c8cf00297b Binary files /dev/null and b/datacenter/dtr/2.1/images/aws-dtr-sg-rules.png differ diff --git a/datacenter/dtr/2.1/images/aws-engine-sg-rules.png b/datacenter/dtr/2.1/images/aws-engine-sg-rules.png new file mode 100644 index 0000000000..0d6d6e821b Binary files /dev/null and b/datacenter/dtr/2.1/images/aws-engine-sg-rules.png differ diff --git a/datacenter/dtr/2.1/images/aws-instance-id.png b/datacenter/dtr/2.1/images/aws-instance-id.png new file mode 100644 index 0000000000..6337bf442a Binary files /dev/null and b/datacenter/dtr/2.1/images/aws-instance-id.png differ diff --git a/datacenter/dtr/2.1/images/azure_filter.png b/datacenter/dtr/2.1/images/azure_filter.png new file mode 100644 index 0000000000..bc89660185 Binary files /dev/null and b/datacenter/dtr/2.1/images/azure_filter.png differ diff --git a/datacenter/dtr/2.1/images/azure_ip.png b/datacenter/dtr/2.1/images/azure_ip.png new file mode 100644 index 0000000000..d42e97bddd Binary files /dev/null and b/datacenter/dtr/2.1/images/azure_ip.png differ diff --git a/datacenter/dtr/2.1/images/azure_portal.png b/datacenter/dtr/2.1/images/azure_portal.png new file mode 100644 index 0000000000..b0507cbed6 Binary files /dev/null and b/datacenter/dtr/2.1/images/azure_portal.png differ diff --git a/datacenter/dtr/2.1/images/basic_configuration.png b/datacenter/dtr/2.1/images/basic_configuration.png new file mode 100644 index 0000000000..c7845b0198 Binary files /dev/null and b/datacenter/dtr/2.1/images/basic_configuration.png differ diff --git a/datacenter/dtr/2.1/images/console-pull.png b/datacenter/dtr/2.1/images/console-pull.png new file mode 100644 index 0000000000..c2d1194bed Binary files /dev/null and b/datacenter/dtr/2.1/images/console-pull.png differ diff --git a/datacenter/dtr/2.1/images/console-push.png b/datacenter/dtr/2.1/images/console-push.png new file mode 100644 index 0000000000..79ddc7d5ef Binary files /dev/null and b/datacenter/dtr/2.1/images/console-push.png differ diff --git a/datacenter/dtr/2.1/images/create-and-manage-orgs-1.png b/datacenter/dtr/2.1/images/create-and-manage-orgs-1.png new file mode 100644 index 0000000000..1b242c0148 Binary files /dev/null and b/datacenter/dtr/2.1/images/create-and-manage-orgs-1.png differ diff --git a/datacenter/dtr/2.1/images/create-and-manage-orgs-2.png b/datacenter/dtr/2.1/images/create-and-manage-orgs-2.png new file mode 100644 index 0000000000..6f010ea345 Binary files /dev/null and b/datacenter/dtr/2.1/images/create-and-manage-orgs-2.png differ diff --git a/datacenter/dtr/2.1/images/create-and-manage-orgs-3.png b/datacenter/dtr/2.1/images/create-and-manage-orgs-3.png new file mode 100644 index 0000000000..a0793bd592 Binary files /dev/null and b/datacenter/dtr/2.1/images/create-and-manage-orgs-3.png differ diff --git a/datacenter/dtr/2.1/images/create-and-manage-teams-1.png b/datacenter/dtr/2.1/images/create-and-manage-teams-1.png new file mode 100644 index 0000000000..3c0c7ac437 Binary files /dev/null and b/datacenter/dtr/2.1/images/create-and-manage-teams-1.png differ diff --git a/datacenter/dtr/2.1/images/create-and-manage-teams-2.png b/datacenter/dtr/2.1/images/create-and-manage-teams-2.png new file mode 100644 index 0000000000..48f69a9c88 Binary files /dev/null and b/datacenter/dtr/2.1/images/create-and-manage-teams-2.png differ diff --git a/datacenter/dtr/2.1/images/create-and-manage-teams-3.png b/datacenter/dtr/2.1/images/create-and-manage-teams-3.png new file mode 100644 index 0000000000..07bcd825e5 Binary files /dev/null and b/datacenter/dtr/2.1/images/create-and-manage-teams-3.png differ diff --git a/datacenter/dtr/2.1/images/create-and-manage-teams-4.png b/datacenter/dtr/2.1/images/create-and-manage-teams-4.png new file mode 100644 index 0000000000..823defa208 Binary files /dev/null and b/datacenter/dtr/2.1/images/create-and-manage-teams-4.png differ diff --git a/datacenter/dtr/2.1/images/create-and-manage-teams-5.png b/datacenter/dtr/2.1/images/create-and-manage-teams-5.png new file mode 100644 index 0000000000..d70972364f Binary files /dev/null and b/datacenter/dtr/2.1/images/create-and-manage-teams-5.png differ diff --git a/datacenter/dtr/2.1/images/create-manage-users-1.png b/datacenter/dtr/2.1/images/create-manage-users-1.png new file mode 100644 index 0000000000..cbf30037c9 Binary files /dev/null and b/datacenter/dtr/2.1/images/create-manage-users-1.png differ diff --git a/datacenter/dtr/2.1/images/create-manage-users-2.png b/datacenter/dtr/2.1/images/create-manage-users-2.png new file mode 100644 index 0000000000..91360649ab Binary files /dev/null and b/datacenter/dtr/2.1/images/create-manage-users-2.png differ diff --git a/datacenter/dtr/2.1/images/dashboard-settings-general.png b/datacenter/dtr/2.1/images/dashboard-settings-general.png new file mode 100644 index 0000000000..f30a948b0c Binary files /dev/null and b/datacenter/dtr/2.1/images/dashboard-settings-general.png differ diff --git a/datacenter/dtr/2.1/images/delete-an-image-1.png b/datacenter/dtr/2.1/images/delete-an-image-1.png new file mode 100644 index 0000000000..beff50eefc Binary files /dev/null and b/datacenter/dtr/2.1/images/delete-an-image-1.png differ diff --git a/datacenter/dtr/2.1/images/docker-hub-org-enterprise-license-CSDE-dropdown.png b/datacenter/dtr/2.1/images/docker-hub-org-enterprise-license-CSDE-dropdown.png new file mode 100644 index 0000000000..fe7a6d2045 Binary files /dev/null and b/datacenter/dtr/2.1/images/docker-hub-org-enterprise-license-CSDE-dropdown.png differ diff --git a/datacenter/dtr/2.1/images/docker-hub-org-enterprise-license.png b/datacenter/dtr/2.1/images/docker-hub-org-enterprise-license.png new file mode 100644 index 0000000000..2f2976f1a3 Binary files /dev/null and b/datacenter/dtr/2.1/images/docker-hub-org-enterprise-license.png differ diff --git a/datacenter/dtr/2.1/images/dtr-integration-1.png b/datacenter/dtr/2.1/images/dtr-integration-1.png new file mode 100644 index 0000000000..a73ef063c1 Binary files /dev/null and b/datacenter/dtr/2.1/images/dtr-integration-1.png differ diff --git a/datacenter/dtr/2.1/images/dtr-license-download.png b/datacenter/dtr/2.1/images/dtr-license-download.png new file mode 100644 index 0000000000..f614e202a8 Binary files /dev/null and b/datacenter/dtr/2.1/images/dtr-license-download.png differ diff --git a/datacenter/dtr/2.1/images/high-availability-1.png b/datacenter/dtr/2.1/images/high-availability-1.png new file mode 100644 index 0000000000..4a7a323764 Binary files /dev/null and b/datacenter/dtr/2.1/images/high-availability-1.png differ diff --git a/datacenter/dtr/2.1/images/high-availability-2.png b/datacenter/dtr/2.1/images/high-availability-2.png new file mode 100644 index 0000000000..c96083a198 Binary files /dev/null and b/datacenter/dtr/2.1/images/high-availability-2.png differ diff --git a/datacenter/dtr/2.1/images/install-dtr-1.png b/datacenter/dtr/2.1/images/install-dtr-1.png new file mode 100644 index 0000000000..c17e7f0d5c Binary files /dev/null and b/datacenter/dtr/2.1/images/install-dtr-1.png differ diff --git a/datacenter/dtr/2.1/images/install-dtr-2.png b/datacenter/dtr/2.1/images/install-dtr-2.png new file mode 100644 index 0000000000..2a284ed12f Binary files /dev/null and b/datacenter/dtr/2.1/images/install-dtr-2.png differ diff --git a/datacenter/dtr/2.1/images/install-dtr-3.png b/datacenter/dtr/2.1/images/install-dtr-3.png new file mode 100644 index 0000000000..37dea664cb Binary files /dev/null and b/datacenter/dtr/2.1/images/install-dtr-3.png differ diff --git a/datacenter/dtr/2.1/images/install-dtr-4.png b/datacenter/dtr/2.1/images/install-dtr-4.png new file mode 100644 index 0000000000..87508be693 Binary files /dev/null and b/datacenter/dtr/2.1/images/install-dtr-4.png differ diff --git a/datacenter/dtr/2.1/images/jenkins-plugins.png b/datacenter/dtr/2.1/images/jenkins-plugins.png new file mode 100644 index 0000000000..82cd8a00f9 Binary files /dev/null and b/datacenter/dtr/2.1/images/jenkins-plugins.png differ diff --git a/datacenter/dtr/2.1/images/jenkins-ui.png b/datacenter/dtr/2.1/images/jenkins-ui.png new file mode 100644 index 0000000000..e828dfbab8 Binary files /dev/null and b/datacenter/dtr/2.1/images/jenkins-ui.png differ diff --git a/datacenter/dtr/2.1/images/license-1.png b/datacenter/dtr/2.1/images/license-1.png new file mode 100644 index 0000000000..58539aa40d Binary files /dev/null and b/datacenter/dtr/2.1/images/license-1.png differ diff --git a/datacenter/dtr/2.1/images/license-2.png b/datacenter/dtr/2.1/images/license-2.png new file mode 100644 index 0000000000..37dea664cb Binary files /dev/null and b/datacenter/dtr/2.1/images/license-2.png differ diff --git a/datacenter/dtr/2.1/images/monitor-1.png b/datacenter/dtr/2.1/images/monitor-1.png new file mode 100644 index 0000000000..87508be693 Binary files /dev/null and b/datacenter/dtr/2.1/images/monitor-1.png differ diff --git a/datacenter/dtr/2.1/images/monitor-2.png b/datacenter/dtr/2.1/images/monitor-2.png new file mode 100644 index 0000000000..c17e7f0d5c Binary files /dev/null and b/datacenter/dtr/2.1/images/monitor-2.png differ diff --git a/datacenter/dtr/2.1/images/overview-1.png b/datacenter/dtr/2.1/images/overview-1.png new file mode 100644 index 0000000000..36153b8a07 Binary files /dev/null and b/datacenter/dtr/2.1/images/overview-1.png differ diff --git a/datacenter/dtr/2.1/images/overview-2.png b/datacenter/dtr/2.1/images/overview-2.png new file mode 100644 index 0000000000..9bb034c54d Binary files /dev/null and b/datacenter/dtr/2.1/images/overview-2.png differ diff --git a/datacenter/dtr/2.1/images/pull-an-image-1.png b/datacenter/dtr/2.1/images/pull-an-image-1.png new file mode 100644 index 0000000000..b95124da2b Binary files /dev/null and b/datacenter/dtr/2.1/images/pull-an-image-1.png differ diff --git a/datacenter/dtr/2.1/images/pull-an-image-2.png b/datacenter/dtr/2.1/images/pull-an-image-2.png new file mode 100644 index 0000000000..d9e91bc86b Binary files /dev/null and b/datacenter/dtr/2.1/images/pull-an-image-2.png differ diff --git a/datacenter/dtr/2.1/images/push-an-image-1.png b/datacenter/dtr/2.1/images/push-an-image-1.png new file mode 100644 index 0000000000..ce53a90d17 Binary files /dev/null and b/datacenter/dtr/2.1/images/push-an-image-1.png differ diff --git a/datacenter/dtr/2.1/images/push-an-image-2.png b/datacenter/dtr/2.1/images/push-an-image-2.png new file mode 100644 index 0000000000..6ec8ae7463 Binary files /dev/null and b/datacenter/dtr/2.1/images/push-an-image-2.png differ diff --git a/datacenter/dtr/2.1/images/push-an-image-3.png b/datacenter/dtr/2.1/images/push-an-image-3.png new file mode 100644 index 0000000000..65e6e8b14d Binary files /dev/null and b/datacenter/dtr/2.1/images/push-an-image-3.png differ diff --git a/datacenter/dtr/2.1/images/repo.png b/datacenter/dtr/2.1/images/repo.png new file mode 100644 index 0000000000..9b08a6bbfc Binary files /dev/null and b/datacenter/dtr/2.1/images/repo.png differ diff --git a/datacenter/dtr/2.1/images/script-copy.png b/datacenter/dtr/2.1/images/script-copy.png new file mode 100644 index 0000000000..3fdf87c7b8 Binary files /dev/null and b/datacenter/dtr/2.1/images/script-copy.png differ diff --git a/datacenter/dtr/2.1/images/use-your-certificates-1.png b/datacenter/dtr/2.1/images/use-your-certificates-1.png new file mode 100644 index 0000000000..c23e89e2aa Binary files /dev/null and b/datacenter/dtr/2.1/images/use-your-certificates-1.png differ diff --git a/datacenter/dtr/2.1/index.md b/datacenter/dtr/2.1/index.md new file mode 100644 index 0000000000..c5cb047a4f --- /dev/null +++ b/datacenter/dtr/2.1/index.md @@ -0,0 +1,48 @@ + + +# Docker Trusted Registry overview + +Docker Trusted Registry (DTR) is the enterprise-grade image storage solution +from Docker. You install it behind your firewall so that you can securely store +and manage the Docker images you use in your applications. + +## Image management + +Docker Trusted Registry can be installed on-premises, or on a virtual private +cloud. And with it, you can store your Docker images securely, behind your +firewall. + +![](images/overview-1.png) + +You can use DTR as part of your continuous integration, and continuous +delivery processes to build, run, and ship your applications. + + +## Built-in security and access control + +DTR uses the same authentication mechanism as Docker Universal Control Plane. +It has a built-in authentication mechanism, and also integrates with LDAP +and Active Directory. It also supports Role Based Access Control (RBAC). + +This allows you to implement fine-grain access control policies, on who has +access to your Docker images. + +![](images/overview-2.png) + + +## Where to go next + +* [DTR architecture](architecture.md) +* [Install DTR](install/index.md) diff --git a/datacenter/dtr/2.1/install/index.md b/datacenter/dtr/2.1/install/index.md new file mode 100644 index 0000000000..6be29b09e7 --- /dev/null +++ b/datacenter/dtr/2.1/install/index.md @@ -0,0 +1,173 @@ + + + +# Install Docker Trusted Registry + +Docker Trusted Registry (DTR) is a containerized application that runs on a +swarm managed by Docker Universal Control Plane (UCP). It can be installed +on-premises or on a cloud infrastructure. + +Use these instructions to install DTR. + +## Step 1. Validate the system requirements + +The first step in installing DTR, is ensuring your +infrastructure has all the [requirements DTR needs to run](system-requirements.md). + +## Step 2. Install UCP + +Since DTR requires Docker Universal Control Plane (UCP) +to run, you need to install UCP on all the nodes where you plan to install DTR. +[Learn how to install UCP](https://docs.docker.com/ucp/installation/install-production/). + +Make sure all the nodes you plan on installing DTR are being managed by UCP. + +## Step 3. Install DTR + +To install DTR you use the `docker/dtr` image. This image has commands to +install, configure, and backup DTR. + +To install DTR: + +1. Get the DTR package. + + ```bash + $ wget https://packages.docker.com/caas/ucp-2.0.0-beta3_dtr-2.1.0-beta3.tar.gz -O docker-datacenter.tar.gz + ``` + +2. Transfer the package to the nodes. + + Now that you have the DTR package in your machine, you can transfer it to the + nodes that you want to install DTR. For each node run: + + ```bash + $ scp docker-datacenter.tag.gz @:/tmp + ``` + +3. Load the images. + + Once the package is on the nodes where you want to install DTR, you can use + the `docker load` command, to load the images from the .tar file. Log + into each node where you plan on installing DTR and run: + + ```bash + $ docker load < /tmp/docker-datacenter.tar.gz + ``` + +4. Download a UCP client bundle. + + Having a UCP client bundle allows you to run Docker commands on a swarm + being managed by UCP. + [Download a UCP client bundle](https://docs.docker.com/ucp/access-ucp/cli-based-access/) + and set up your CLI client to use it. + +5. Run the following commands to install DTR. + + ```bash + + # Install DTR + $ docker run -it --rm \ + docker/dtr:2.1.0-beta3 install \ + --ucp-node \ + --ucp-insecure-tls + ``` + + Where the `--ucp-node` is the hostname of the node where you've previously + loaded the DTR images, and `--ucp-insecure-tls` tells the installer to + trust the certificates used by UCP. + The install command has other flags for customizing DTR at install time. + Check the [reference documentation to learn more](../reference/install.md). + + +6. Check that DTR is running. + + In your browser, navigate to the the Docker **Universal Control Plane** + web UI, and navigate to the **Applications** screen. DTR should be listed + as an application. + + ![](../images/install-dtr-1.png) + + You can also access the **DTR web UI**, to make sure it is working. In your + browser, navigate to the address were you installed DTR. + + ![](../images/install-dtr-2.png) + + +## Step 4. Configure DTR + +After installing DTR, you should configure: + + * The Domain Name used to access DTR, + * The certificates used for TLS communication, + * The storage backend to store the Docker images. + + To perform these configurations, navigate to the **Settings** page of DTR. + + ![](../images/install-dtr-3.png) + +## Step 5. Test pushing and pulling + +Now that you have a working installation of DTR, you should test that you can +push and pull images to it. +[Learn how to push and pull images](../repos-and-images/index.md). + +## Step 6. Join replicas to the cluster + +This step is optional. + +To set up DTR for [high availability](../high-availability/index.md), +you can add more replicas to your DTR cluster. Adding more replicas allows you +to load-balance requests across all replicas, and keep DTR working if a +replica fails. + +For high-availability you should set 3, 5, or 7 DTR replicas. The nodes where +you're going to install these replicas also need to be managed by UCP. + +To add replicas to a DTR cluster, use the `docker/dtr join` command. To add +replicas: + +1. Make sure the DTR images are loaded into the node. + +2. Load you UCP user bundle. + +3. Run the join command. + + When you join a replica to a DTR cluster, you need to specify the + ID of a replica that is already part of the cluster. You can find an + existing replica ID by going to the **Applications** page on UCP. + + Then run: + + ```bash + $ docker run -it --rm \ + docker/dtr:2.1.0-beta3 join \ + --ucp-node \ + --ucp-insecure-tls + ``` + +4. Check that all replicas are running. + + In your browser, navigate to the the Docker **Universal Control Plane** + web UI, and navigate to the **Applications** screen. All replicas should + be displayed. + + ![](../images/install-dtr-4.png) + +## See also + +* [Install DTR offline](install-dtr-offline.md) +* [Upgrade DTR](upgrade/upgrade-major.md) diff --git a/datacenter/dtr/2.1/install/install-dtr-offline.md b/datacenter/dtr/2.1/install/install-dtr-offline.md new file mode 100644 index 0000000000..0909267452 --- /dev/null +++ b/datacenter/dtr/2.1/install/install-dtr-offline.md @@ -0,0 +1,63 @@ + + + +# Install DTR offline + +The procedure to install Docker Trusted Registry on a node is the same, +whether that node has access to the internet or not. + +The only difference when installing DTR on an offline node, is that instead +of pulling the DTR images from Docker Hub, you use a computer that is connected +to the internet to download a single package with all DTR images. Then you +copy that package to the nodes where you’ll install DTR. + +1. Get the DTR package. + + Use a computer with internet access to download a single package with all + Docker Datacenter components: + + ```bash + $ wget https://packages.docker.com/caas/ucp-2.0.0-beta3_dtr-2.1.0-beta3.tar.gz -O docker-datacenter.tar.gz + ``` + +2. Transfer the package to the offline nodes. + + Now that you have the DTR package in your machine, you can transfer it to the + nodes that you want to install DTR. For each node run: + + ```bash + $ scp docker-datacenter.tag.gz @:/tmp + ``` + +3. Login into the nodes where you transferred the images. + +4. Load the images. + + Once the package is on the nodes where you want to install DTR, you can use + the `docker load` command, to load the images from the .tar file. On each + node, run: + + ```bash + $ docker load < /tmp/docker-datacenter.tar.gz + ``` + +5. Install DTR. + + Now that the offline node has all the images needed to install DTR, + you can [install DTR that host](index.md). + + +## Where to go next + +* [DTR architecture](../architecture.md) +* [Install DTR](index.md) diff --git a/datacenter/dtr/2.1/install/license.md b/datacenter/dtr/2.1/install/license.md new file mode 100644 index 0000000000..dab91114c8 --- /dev/null +++ b/datacenter/dtr/2.1/install/license.md @@ -0,0 +1,50 @@ + + + +# License DTR + +By default, you don't need to license your Docker Trusted Registry. When +installing DTR, it automatically starts using the same license file used on +your Docker Universal Control Plane cluster. + +However, there are some situations when you have to manually license your +DTR installation: + +* When upgrading to a new major version, +* When your current license expires. + + +## Download your license + +Go to [Docker Store](https://store.docker.com/bundles/docker-datacenter) and +download your license. + +![](../images/license-1.png) + + +## License your installation + +Once you've downloaded the license file, you can apply it to your DTR +installation. Navigate to the **DTR web UI**, and then go to the **Settings +page**. + +![](../images/license-2.png) + +Click the **Apply new license** button, and upload your new license file. + + +## Where to go next + +* [Install DTR](index.md) +* [Install DTR offline](install-dtr-offline.md) diff --git a/datacenter/dtr/2.1/install/menu.md b/datacenter/dtr/2.1/install/menu.md new file mode 100644 index 0000000000..e79d2b19e0 --- /dev/null +++ b/datacenter/dtr/2.1/install/menu.md @@ -0,0 +1,12 @@ + diff --git a/datacenter/dtr/2.1/install/system-requirements.md b/datacenter/dtr/2.1/install/system-requirements.md new file mode 100644 index 0000000000..5b8ed80f7f --- /dev/null +++ b/datacenter/dtr/2.1/install/system-requirements.md @@ -0,0 +1,50 @@ + + + +# DTR system requirements + +Docker Trusted Registry can be installed on-premises or on the cloud. +Before installing, be sure your infrastructure has these requirements. + +## Software requirements + +You can only install DTR on a node that is being managed by Docker Universal +Control Plane 2.0. + + +## Ports used + +When installing DTR on a node, make sure the following ports are open on that +node: + +| Direction | Port | Purpose | +|:---------:|:-----|:--------------------------------------| +| in | 80 | Web app and API client access to DTR. | +| in | 443 | Web app and API client access to DTR. | + +These ports are configurable when installing DTR. + +## Compatibility and maintenance lifecycle + +Docker Datacenter is a software subscription that includes 3 products: + +* CS Docker Engine, +* Docker Trusted Registry, +* Docker Universal Control Plane. + +[Learn more about the maintenance lifecycle for these products](http://success.docker.com/Get_Help/Compatibility_Matrix_and_Maintenance_Lifecycle). + +## Where to go next + +* [DTR architecture](../architecture.md) +* [Install DTR](index.md) diff --git a/datacenter/dtr/2.1/install/uninstall.md b/datacenter/dtr/2.1/install/uninstall.md new file mode 100644 index 0000000000..576a2d9f16 --- /dev/null +++ b/datacenter/dtr/2.1/install/uninstall.md @@ -0,0 +1,67 @@ + + +# Uninstall Docker Trusted Registry + +Use the `remove` command, to remove a DTR replica from a cluster. +To uninstall a DTR cluster you remove all DTR replicas one at a time. +The remove command: + +* Removes the replica from the cluster, +* Stops and removes all DTR containers, +* Deletes all DTR volumes. + +To see what options are available in the uninstall command, check the +[uninstall command reference](../reference/remove.md), or run: + +```bash +$ docker run -it --rm docker/dtr:2.1.0-beta3 remove --help +``` + +To remove a replica safely, you must tell the bootstrapper about one healthy replica +using the `--existing-replica-id` flag and the replica to remove with the +`--replica-id` flag. It uses the healthy replica to safely inform your DTR cluster +that the replica is about to be removed before it performs the actual removal. + +## Example + +The following example illustrates how use the remove command interactively to +remove a DTR replica from a cluster with multiple replicas: + +```bash + +$ docker run -it --rm \ + docker/dtr:2.1.0-beta3 remove \ + --ucp-insecure-tls + +existing-replica-id (ID of an existing replica in a cluster): 7ae3cb044b70 +replica-id (Specify the replica Id. Must be unique per replica, leave blank for random): a701a510126c +ucp-username (Specify the UCP admin username): $UCP_ADMIN +ucp-password: $UCP_PASSWORD +ucp-url (Specify the UCP host using the host[:port] format): $UCP_HOST +``` + +Where: + +* existing-replica-id: is the id of any healthy DTR replica of that cluster, +* replica-id: is the id of the DTR replica you want to remove, +* ucp-username and ucp-password: are the username and password of a UCP administrator. + + +Now you can confirm on Docker Universal Control Plane that the DTR replica +`a701a510126c` no longer exists. + + +## Where to go next + +* [Install DTR](index.md) +* [Install DTR offline](install-dtr-offline.md) diff --git a/datacenter/dtr/2.1/install/upgrade/index.md b/datacenter/dtr/2.1/install/upgrade/index.md new file mode 100644 index 0000000000..18ce8eb691 --- /dev/null +++ b/datacenter/dtr/2.1/install/upgrade/index.md @@ -0,0 +1,71 @@ + + +# Upgrade from 2.0.0 + + + +> You can't upgrade from one beta version to another. To test the latest +> beta version, start by uninstalling the previous version. + +The first step in upgrading to a new minor version or patch release of DTR 2.0, +is ensuring you're running DTR 2.0. If that's not the case, start by upgrading +your installation to version 2.0.0, and then upgrade to the latest version +available. + +There is no downtime when upgrading an highly-available DTR cluster. If your +DTR deployment has a single replica, schedule the upgrade to take place outside +business peak hours to ensure the impact on your business is close to none. + +## Step 1. Upgrade DTR to 2.0 + +Make sure you're running DTR 2.0. If that's not the case, [upgrade your +installation to the 2.0 version](upgrade-major.md). + +## Step 2. Upgrade DTR + +To upgrade DTR you use the `upgrade` command. + +1. Download a UCP client bundle. + + Having a UCP client bundle allows you to run Docker commands on a UCP + cluster. Download a UCP client bundle and set up your CLI client to use it. + +2. Pull the latest `docker/dtr` image. + + ```bash + $ docker pull docker/dtr: + ``` + + If the node you're upgrading doesn't have access to the internet, you can + use a machine with internet connection to + [pull all the DTR images](../install-dtr-offline.md). + +4. Run the upgrade command. + + The upgrade command upgrades all DTR replicas that are part of your cluster: + + ```bash + $ docker run -it --rm \ + docker/dtr: upgrade \ + --ucp-insecure-tls + ``` + + By default the upgrade command runs in interactive mode and prompts you for + any necessary information. You can also check the + [reference documentation](../reference/index.md) for other existing flags. + +## Where to go next + +* [Upgrade to DTR 2.0](upgrade-major.md) +* [Monitor DTR](../../monitor-troubleshoot/index.md) diff --git a/datacenter/dtr/2.1/install/upgrade/menu.md b/datacenter/dtr/2.1/install/upgrade/menu.md new file mode 100644 index 0000000000..55f888ae16 --- /dev/null +++ b/datacenter/dtr/2.1/install/upgrade/menu.md @@ -0,0 +1,12 @@ + diff --git a/datacenter/dtr/2.1/install/upgrade/upgrade-major.md b/datacenter/dtr/2.1/install/upgrade/upgrade-major.md new file mode 100644 index 0000000000..1b98460833 --- /dev/null +++ b/datacenter/dtr/2.1/install/upgrade/upgrade-major.md @@ -0,0 +1,209 @@ + + +# Upgrade from DTR 1.4.3 + +The first step in upgrading to Docker Trusted Registry (DTR) 2.0, is ensuring +you are running DTR 1.4.3. If that's not the case, start by upgrading your +installation to version 1.4.3, and then upgrade to DTR 2.0. + +To upgrade from DTR 1.4.3 to 2.0 you first need to do a fresh installation of +DTR 2.0. Then you migrate the data from your DTR 1.4.3 installation to the 2.0 +installation. Finally, you decommission your 1.4.3 by uninstalling it. + +## Step 1. Upgrade DTR to 1.4.3 + +Make sure you're running DTR 1.4.3. If that's not the case, upgrade your +installation to the 1.4.3 version. + +## Step 2. Install DTR 2.0 + +To upgrade to DTR 2.0, you first need to do a fresh installation of DTR 2.0. +This can be done on the same node where DTR 1.4.3 is already running or on a +new node. + +If you decide to install the new DTR on the same node, you'll need +to install it on a port other than 443, since DTR 1.4.3 is already using it. +Use these instructions to install DTR 2.0: + +* [Release notes](../../release-notes/index.md) +* [System requirements](../system-requirements.md) +* [DTR architecture](../../architecture.md) +* [Install DTR 2.0](../index.md) + + +## Step 3. Migrate metadata + +Once you have your DTR 1.4.3 and the new DTR 2.0 running, you can migrate +configurations, accounts, and repository metadata from one installation to +another. + +For this, you can use the `docker/dtr migrate` command. This command +migrates configurations, accounts, and repository metadata. It doesn't migrate +the images that are on the storage backend used by DTR 1.4.3. + +Before running the migration, get the DTR 2.0 CA certificate used for the `--dtr-ca` parameter: + +1. Log into the **DTR 2.0 web UI**, and navigate to the **Settings** screen. + +2. In the **Domain** section, click the **Show TLS settings** link. + +3. Copy the content of the **TLS CA** field. + + ![](../../images/dtr-integration-1.png) + +To start the migration: + +1. Log into the host running DTR 1.4.3 using ssh. + +2. Use the docker/dtr migrate command. + + When you run the docker/dtr migrate command, Docker pulls the necessary + images from Docker Hub. If the the host where DTR 1.4.3 is not connected + to the internet, you need to + [download the images to the host](../install-dtr-offline.md). + + Then run the migrate command: + + ```bash + # Migrate configurations, accounts, and repository metadata + docker run -it --rm \ + -v /var/run/docker.sock:/var/run/docker.sock \ + docker/dtr migrate \ + --ucp-url $UCP_HOST \ + --dtr-external-url $DTR_HOST \ + --ucp-insecure-tls \ + --dtr-ca "$(cat dtrca.crt)" + ``` + +## Step 4. Validate your configurations + +After the migration finishes, test your DTR 2.0 installation to make sure it is +properly configured. +In your browser navigate to the DTR 2.0 **Settings page**, and check that DTR: + +* Is correctly licensed, +* The storage backend is correctly configured, +* The user authentication method is correctly configured. + +You need to manually configure the following settings: + +* Domain name, +* Certificates. + +You can find the certificates of DTR 1.4.3 under `/usr/local/etc/dtr/ssl`. + +## Step 5. Transfer image data to DTR 2.0 + +If utilizing local filesystem storage, the image data is not copied during by +the migrate command and should be transferred manually. + +To transfer the images: + +1. Log into the host running DTR 2.0 using ssh. + +2. Get the filesystem volume path DTR 2.0 stores images: + + ```bash + $ docker volume inspect --format '{{ .Mountpoint }}' $(docker volume ls -q | grep dtr-registry) + ``` + + The path returned will be similar to: `/var/lib/docker/volumes/dtr-registry-fa61225dc006/_data` + +3. Log into the host running DTR 1.4.3 using ssh. + +4. Copy the image data: + + ```bash + $ scp -r /var/local/dtr/image-storage/local/* $DTR_HOST:$DTR_2_FS_VOLUME_PATH + ``` + + For example: + + ```bash + $ scp -r /var/local/dtr/image-storage/local/* \ + dtr2:/var/lib/docker/volumes/dtr-registry-4fb637dbbecc/_data/ + ``` + +## Step 6. Test your installation + +Now that you have a working installation of DTR 2.0, you should test that you +can push and pull images to it. +[Learn how to push and pull images](../../repos-and-images/pull-an-image.md). + +## Step 7. Join replicas to your cluster + +This step is optional. + +To set up DTR for [high availability](../../high-availability/index.md), +you can add more replicas to your DTR cluster. Adding more replicas allows you +to load-balance requests across all replicas, and keep DTR working if a +replica fails. + +To add replicas to a DTR cluster, use the `docker/dtr join` command. To add +replicas: + + +1. Load you UCP user bundle. + +2. Run the join command. + + When you join a replica to a DTR cluster, you need to specify the + ID of a replica that is already part of the cluster. You can find an + existing replica ID by going to the **Applications** page on UCP. + + Then run: + + ```bash + $ docker run -it --rm \ + docker/dtr join \ + --ucp-url $UCP_URL \ + --ucp-node $UCP_NODE \ + --existing-replica-id $REPLICA_TO_JOIN \ + --ucp-username $USER --ucp-password $PASSWORD \ + --ucp-insecure-tls + ``` + + Where: + + * ucp-url, is the URL of the UCP controller, + * ucp-node, is the node on the ucp cluster where the DTR replica will be installed, + * existing-replica-id, is the ID of the DTR replica you want to replicate, + * ucp-username, and ucp-password are the credentials of a UCP administrator, + * ucp-ca, is the certificate used by UCP. + +3. Check that all replicas are running. + + In your browser, navigate to the the Docker **Universal Control Plane** + web UI, and navigate to the **Applications** screen. All replicas should + be displayed. + + ![](../../images/install-dtr-4.png) + +4. Follow steps 1 to 3, to add more replicas to the DTR cluster. + + When configuring your DTR cluster for high-availability, you should install + 3, 5, or 7 replicas. + [Learn more about high availability](../../high-availability/index.md) + +## Step 8. Decommission DTR 1.4.3 + +Once you've fully tested your new installation, you can uninstall DTR 1.4.3 +by deleting `/usr/local/etc/dtr` and `/var/local/dtr` and removing all dtr +containers. + +## Where to go next + +* [Upgrade to DTR 2.x](index.md) +* [Monitor DTR](../../monitor-troubleshoot/index.md) diff --git a/datacenter/dtr/2.1/menu.md b/datacenter/dtr/2.1/menu.md new file mode 100644 index 0000000000..7557cd492d --- /dev/null +++ b/datacenter/dtr/2.1/menu.md @@ -0,0 +1,11 @@ + diff --git a/datacenter/dtr/2.1/monitor-troubleshoot/index.md b/datacenter/dtr/2.1/monitor-troubleshoot/index.md new file mode 100644 index 0000000000..eec0978265 --- /dev/null +++ b/datacenter/dtr/2.1/monitor-troubleshoot/index.md @@ -0,0 +1,40 @@ + + +# Monitor DTR + +Docker Trusted Registry is a Dockerized application. To monitor it, you can +use the same tools and techniques you're already using to monitor other +containerized applications running on your cluster. One way to monitor +DTR is using the monitoring capabilities of Docker Universal Control Plane. + +In your browser, log in to **Docker Universal Control Plane** (UCP), and +navigate to the **Applications** page. + +To make it easier to find DTR, use the search box to **search for the +DTR application**. If you have DTR set up for high-availability, then all the +DTR nodes are displayed. + +![](../images/monitor-1.png) + +**Click on the DTR application** to see all of its containers, and if they're +running. **Click on a container** to see its details, like configurations, +resources, and logs. + +![](../images/monitor-2.png) + + +## Where to go next + +* [Troubleshoot DTR](troubleshoot.md) +* [DTR architecture](../architecture.md) diff --git a/datacenter/dtr/2.1/monitor-troubleshoot/menu.md b/datacenter/dtr/2.1/monitor-troubleshoot/menu.md new file mode 100644 index 0000000000..26770fbe56 --- /dev/null +++ b/datacenter/dtr/2.1/monitor-troubleshoot/menu.md @@ -0,0 +1,12 @@ + diff --git a/datacenter/dtr/2.1/monitor-troubleshoot/troubleshoot.md b/datacenter/dtr/2.1/monitor-troubleshoot/troubleshoot.md new file mode 100644 index 0000000000..71673485a9 --- /dev/null +++ b/datacenter/dtr/2.1/monitor-troubleshoot/troubleshoot.md @@ -0,0 +1,73 @@ + + +# Troubleshoot DTR + +## Overlay networking + +High availability in DTR depends on having overlay networking working in UCP. +To manually test that overlay networking is working in UCP run the following +commands on two different UCP machines. + +``` +docker run -it --rm --net dtr-ol --name overlay-test1 --entrypoint sh docker/dtr +docker run -it --rm --net dtr-ol --name overlay-test2 --entrypoint ping docker/dtr -c 3 overlay-test1 +``` + +You can create new new overlay network for this test with `docker network create -d overaly network-name`. +You can also use any images that contain `sh` and `ping` for this test. + +If the second command succeeds, overlay networking is working. + +## DTR doesn't come up after a Docker restart + +This is a known issue with Docker restart policies when DTR is running on the same +machine as a UCP controller. If this happens, you can simply restart the DTR replica +from the UCP UI under "Applications". The best workaround right now is to not run +DTR on the same node as a UCP controller. + +## Etcd refuses to start after a Docker restart + +If you see the following log message in etcd's logs after a DTR restart it means that +your DTR replicas are on machines that don't have their clocks synchronized. Etcd requires +synchronized clocks to function correctly. + +``` +2016-04-27 17:56:34.086748 W | rafthttp: the clock difference against peer aa4fdaf4c562342d is too high [8.484795885s > 1s] +``` + +## Accessing the RethinkDB Admin UI + + > Warning: This command will expose your database to the internet with no authentication. Use with caution. + +Run this on the UCP node that has a DTR replica with the given replica id: + +``` +docker run --rm -it --net dtr-br -p 9999:8080 svendowideit/ambassador dtr-rethinkdb-$REPLICA_ID 8080 +``` + +Options to make this more secure: + +* Use `-p 127.0.0.1:9999:8080` to expose the admin UI only to localhost +* Use an SSH tunnel in combination with exposing the port only to localhost +* Use a firewall to limit which IPs are allowed to connect +* Use a second proxy with TLS and basic auth to provide secure access over the Internet + +## Accessing etcd directly + +You can execute etcd commands on a UCP node hosting a DTR replica using etcdctl +via the following docker command: + +``` +docker run --rm -v dtr-ca-$REPLICA_ID:/ca --net dtr-br -it --entrypoint /etcdctl docker/dtr-etcd:v2.2.4 --endpoint https://dtr-etcd-$REPLICA_ID.dtr-br:2379 --ca-file /ca/etcd/cert.pem --key-file /ca/etcd-client/key.pem --cert-file /ca/etcd-client/cert.pem +``` diff --git a/datacenter/dtr/2.1/reference/backup.md b/datacenter/dtr/2.1/reference/backup.md new file mode 100644 index 0000000000..8f5ca87a37 --- /dev/null +++ b/datacenter/dtr/2.1/reference/backup.md @@ -0,0 +1,59 @@ + + +# docker/dtr backup + +Create a backup of DTR + +## Usage + +```bash +docker run -i --rm docker/dtr \ + backup [command options] > backup.tar +``` + +## Description + + +This command creates a tar file with the contents of the volumes used by +DTR, and prints it. You can then use the 'restore' command to restore the data +from an existing backup. + +Note: + + * This command only creates backups of configurations, and image metadata. + It doesn't backup users and organizations. Users and organizations can be + backed up when performing a UCP backup. + + It also doesn't backup the Docker images stored in your registry. + You should implement a separate backup policy for the Docker images stored + in your registry, taking in consideration whether your DTR installation is + configured to store images on the filesystem or using a cloud provider. + + * This backup contains sensitive information and should be + stored securely. + + +## Options + +| Option | Description | +|:--------------------------|:---------------------------| +|`--ucp-url`|The UCP URL including domain and port| +|`--ucp-username`|The UCP administrator username| +|`--ucp-password`|The UCP administrator password| +|`--debug`|Enable debug mode for additional logging| +|`--hub-username`|Username to use when pulling images| +|`--hub-password`|Password to use when pulling images| +|`--ucp-insecure-tls`|Disable TLS verification for UCP| +|`--ucp-ca`|Use a PEM-encoded TLS CA certificate for UCP| +|`--existing-replica-id`|The ID of an existing DTR replica| +|`--config-only`|Backup/restore only the configurations of DTR and not the database| + diff --git a/datacenter/dtr/2.1/reference/dumpcerts.md b/datacenter/dtr/2.1/reference/dumpcerts.md new file mode 100644 index 0000000000..2c1da74923 --- /dev/null +++ b/datacenter/dtr/2.1/reference/dumpcerts.md @@ -0,0 +1,43 @@ + + +# docker/dtr dumpcerts + +Print the TLS certificates used by DTR + +## Usage + +```bash +docker run -i --rm docker/dtr \ + dumpcerts [command options] > backup.tar +``` + +## Description + + +This command creates a backup of the certificates used by DTR for +communicating across replicas with TLS. + + +## Options + +| Option | Description | +|:--------------------------|:---------------------------| +|`--ucp-url`|The UCP URL including domain and port| +|`--ucp-username`|The UCP administrator username| +|`--ucp-password`|The UCP administrator password| +|`--debug`|Enable debug mode for additional logging| +|`--hub-username`|Username to use when pulling images| +|`--hub-password`|Password to use when pulling images| +|`--ucp-insecure-tls`|Disable TLS verification for UCP| +|`--ucp-ca`|Use a PEM-encoded TLS CA certificate for UCP| +|`--existing-replica-id`|The ID of an existing DTR replica| + diff --git a/datacenter/dtr/2.1/reference/images.md b/datacenter/dtr/2.1/reference/images.md new file mode 100644 index 0000000000..907d67be24 --- /dev/null +++ b/datacenter/dtr/2.1/reference/images.md @@ -0,0 +1,29 @@ + + +# docker/dtr images + +List all the images necessary to install DTR + +## Usage + +```bash +docker run -it --rm docker/dtr \ + images [command options] +``` + +## Description + + +This command lists all the images necessary to install DTR. + + + diff --git a/datacenter/dtr/2.1/reference/index.md b/datacenter/dtr/2.1/reference/index.md new file mode 100644 index 0000000000..2371f24bc7 --- /dev/null +++ b/datacenter/dtr/2.1/reference/index.md @@ -0,0 +1,44 @@ + + +# docker/dtr overview + +This tool has commands to install, configure, and backup Docker +Trusted Registry (DTR). It also allows uninstalling DTR. +By default the tool runs in interactive mode. It prompts you for +the values needed. + +Additional help is available for each command with the '--help' option. + + +## Usage + +```bash +docker run -it --rm docker/dtr \ + command [command options] +``` + + +## Commands + +| Option | Description | +|:-----------------------------|:---------------------------| +|`install`| Install Docker Trusted Registry| +|`join`| Add a new replica to an existing DTR cluster| +|`reconfigure`| Change DTR configurations| +|`remove`| Remove a DTR replica| +|`restore`| Install and restore DTR from an existing backup| +|`backup`| Create a backup of DTR| +|`upgrade`| Upgrade DTR 2.0.0 or later cluster to this version| +|`dumpcerts`| Print the TLS certificates used by DTR| +|`images`| List all the images necessary to install DTR| + diff --git a/datacenter/dtr/2.1/reference/install.md b/datacenter/dtr/2.1/reference/install.md new file mode 100644 index 0000000000..8445609103 --- /dev/null +++ b/datacenter/dtr/2.1/reference/install.md @@ -0,0 +1,68 @@ + + +# docker/dtr install + +Install Docker Trusted Registry + +## Usage + +```bash +docker run -it --rm docker/dtr \ + install [command options] +``` + +## Description + + +This command installs Docker Trusted Registry (DTR) on a node managed by +Docker Universal Control Plane (UCP). + +After installing DTR, you can join additional DTR replicas using the 'join' +command. + + +## Options + +| Option | Description | +|:--------------------------|:---------------------------| +|`--ucp-url`|The UCP URL including domain and port| +|`--ucp-username`|The UCP administrator username| +|`--ucp-password`|The UCP administrator password| +|`--debug`|Enable debug mode for additional logging| +|`--hub-username`|Username to use when pulling images| +|`--hub-password`|Password to use when pulling images| +|`--http-proxy`|The HTTP proxy used for outgoing requests| +|`--https-proxy`|The HTTPS proxy used for outgoing requests| +|`--no-proxy`|Don't use a proxy for these domains. Format acme.org[, acme.com]| +|`--replica-http-port`|The public HTTP port for the DTR replica. Default is 80| +|`--replica-https-port`|The public HTTPS port for the DTR replica. Default is 443| +|`--log-protocol`|The protocol for sending container logs: tcp, tcp+tls, udp or internal. Default: internal| +|`--log-host`|Endpoint to send logs to, required if --log-protocol is tcp or udp| +|`--log-level`|Log level for container logs. Default: INFO| +|`--log-tls-ca-cert`|PEM-encoded TLS CA cert for DTR logging driver. Ignored if the logging protocol is not tcp+tls| +|`--log-tls-cert`|PEM-encoded TLS cert for DTR logging driver. Ignored if the logging protocol is not tcp+tls| +|`--log-tls-key`|PEM-encoded TLS key for DTR logging driver. Ignored if the address protocol is not tcp+tls| +|`--log-tls-skip-verify`|Disable TLS verification for the logging service. Ignored if the logging address is not tcp+tls| +|`--dtr-external-url`|URL of the host or load balancer clients use to reach DTR. Format https://host[:port]| +|`--dtr-storage-volume`|Full path or volume name to store Docker images in the local filesystem| +|`--nfs-storage-url`|NFS to store Docker images. Requires NFS client libraries. Format nfs:///| +|`--enable-pprof`|Enables pprof profiling of the server| +|`--etcd-heartbeat-interval`|Frequency in milliseconds that the key-value store leader notifies followers| +|`--etcd-election-timeout`|Timeout in milliseconds for key-value store membership| +|`--etcd-snapshot-count`|Number of changes between key-value store snapshots| +|`--ucp-insecure-tls`|Disable TLS verification for UCP| +|`--ucp-ca`|Use a PEM-encoded TLS CA certificate for UCP| +|`--ucp-node`|The hostname of the node to install DTR| +|`--replica-id`|Assign an ID to the DTR replica. By default the ID is random| +|`--unsafe`|Allow DTR to be installed on a UCP manager node| +|`--extra-envs`|Environment variables or swarm constraints for DTR containers. Format var=val[&var=val]| + diff --git a/datacenter/dtr/2.1/reference/join.md b/datacenter/dtr/2.1/reference/join.md new file mode 100644 index 0000000000..117560164d --- /dev/null +++ b/datacenter/dtr/2.1/reference/join.md @@ -0,0 +1,47 @@ + + +# docker/dtr join + +Add a new replica to an existing DTR cluster + + + +## Description + + +This command creates a replica of an existing DTR on a node managed by +Docker Universal Control Plane (UCP). + +For setting DTR for high-availability, create 3, 5, or 7 replicas of DTR. + + +## Options + +| Option | Description | +|:--------------------------|:---------------------------| +|`--ucp-url`|The UCP URL including domain and port| +|`--ucp-username`|The UCP administrator username| +|`--ucp-password`|The UCP administrator password| +|`--debug`|Enable debug mode for additional logging| +|`--hub-username`|Username to use when pulling images| +|`--hub-password`|Password to use when pulling images| +|`--ucp-insecure-tls`|Disable TLS verification for UCP| +|`--ucp-ca`|Use a PEM-encoded TLS CA certificate for UCP| +|`--ucp-node`|The hostname of the node to install DTR| +|`--replica-id`|Assign an ID to the DTR replica. By default the ID is random| +|`--unsafe`|Allow DTR to be installed on a UCP manager node| +|`--existing-replica-id`|The ID of an existing DTR replica| +|`--replica-http-port`|The public HTTP port for the DTR replica. Default is 80| +|`--replica-https-port`|The public HTTPS port for the DTR replica. Default is 443| +|`--skip-network-test`|Don't test if overlay networks are working correctly between UCP nodes| +|`--extra-envs`|Environment variables or swarm constraints for DTR containers. Format var=val[&var=val]| + diff --git a/datacenter/dtr/2.1/reference/menu.md b/datacenter/dtr/2.1/reference/menu.md new file mode 100644 index 0000000000..ca6363f184 --- /dev/null +++ b/datacenter/dtr/2.1/reference/menu.md @@ -0,0 +1,12 @@ + diff --git a/datacenter/dtr/2.1/reference/migrate.md b/datacenter/dtr/2.1/reference/migrate.md new file mode 100644 index 0000000000..9c77d0db3d --- /dev/null +++ b/datacenter/dtr/2.1/reference/migrate.md @@ -0,0 +1,51 @@ + + +# docker/dtr migrate + +Migrate configurations, accounts, and repository metadata from DTR 1.4.3 to 2.0. +Only available in `docker/dtr` version 2.0.x. + +## Usage + +```bash +$ docker run -it --rm docker/dtr \ + migrate [command options] +``` + +## Description + +This command migrates configurations, accounts, and repository metadata from +Docker Trusted Registry 1.4.3 to 2.0. + +To upgrade from DTR 1.4.3 to 2.0 you first need to do a fresh installation of +DTR 2.0. Then you run this command on the host where DTR 1.4.3 is running, to +migrate the data to the new installation. Finally, you decommission your +DTR 1.4.3 by uninstalling it. + + +| Option | Description | +|:-----------------------|:-------------------------------------------------------------------------------------| +| `--ucp-url ` | Specify the UCP controller URL [$UCP_URL] | +| `--ucp-username` | Specify the UCP admin username [$UCP_USERNAME] | +| `--ucp-password` | Specify the UCP admin password [$UCP_PASSWORD] | +| `--debug` | Enable debug mode, provides additional logging [$DEBUG] | +| `--hub-username` | Specify the Docker Hub username for pulling images [$HUB_USERNAME] | +| `--hub-password` | Specify the Docker Hub password for pulling images [$HUB_PASSWORD] | +| `--ucp-insecure-tls` | Disable TLS verification for UCP [$UCP_INSECURE_TLS] | +| `--ucp-ca` | Use a PEM-encoded TLS CA certificate for UCP [$UCP_CA] | +| `--run-full-migration` | Run full migration procedure instead of dumping configurations [$RUN_FULL_MIGRATION] | +| `--dtr-load-balancer` | Specify the domain name and port for the DTR load balancer [$DTR_LOAD_BALANCER] | +| `--dtr-insecure-tls` | Disable TLS verification for DTR [$DTR_INSECURE_TLS] | +| `--dtr-ca` | PEM-encoded TLS CA cert for DTR [$DTR_CA] | +| `--http-proxy` | Set the HTTP proxy for outgoing requests [$DTR_HTTP_PROXY] | +| `--https-proxy` | Set the HTTPS proxy for outgoing requests [$DTR_HTTPS_PROXY] | +| `--no-proxy` | Set the list of domains to not proxy to [$DTR_NO_PROXY] | diff --git a/datacenter/dtr/2.1/reference/reconfigure.md b/datacenter/dtr/2.1/reference/reconfigure.md new file mode 100644 index 0000000000..b92110cacb --- /dev/null +++ b/datacenter/dtr/2.1/reference/reconfigure.md @@ -0,0 +1,64 @@ + + +# docker/dtr reconfigure + +Change DTR configurations + +## Usage + +```bash +docker run -it --rm docker/dtr \ + reconfigure [command options] +``` + +## Description + + +This command changes DTR configuration settings. + +DTR is restarted for the new configurations to take effect. To have no down +time, configure your DTR for high-availability. + + +## Options + +| Option | Description | +|:--------------------------|:---------------------------| +|`--ucp-url`|The UCP URL including domain and port| +|`--ucp-username`|The UCP administrator username| +|`--ucp-password`|The UCP administrator password| +|`--debug`|Enable debug mode for additional logging| +|`--hub-username`|Username to use when pulling images| +|`--hub-password`|Password to use when pulling images| +|`--http-proxy`|The HTTP proxy used for outgoing requests| +|`--https-proxy`|The HTTPS proxy used for outgoing requests| +|`--no-proxy`|Don't use a proxy for these domains. Format acme.org[, acme.com]| +|`--replica-http-port`|The public HTTP port for the DTR replica. Default is 80| +|`--replica-https-port`|The public HTTPS port for the DTR replica. Default is 443| +|`--log-protocol`|The protocol for sending container logs: tcp, tcp+tls, udp or internal. Default: internal| +|`--log-host`|Endpoint to send logs to, required if --log-protocol is tcp or udp| +|`--log-level`|Log level for container logs. Default: INFO| +|`--log-tls-ca-cert`|PEM-encoded TLS CA cert for DTR logging driver. Ignored if the logging protocol is not tcp+tls| +|`--log-tls-cert`|PEM-encoded TLS cert for DTR logging driver. Ignored if the logging protocol is not tcp+tls| +|`--log-tls-key`|PEM-encoded TLS key for DTR logging driver. Ignored if the address protocol is not tcp+tls| +|`--log-tls-skip-verify`|Disable TLS verification for the logging service. Ignored if the logging address is not tcp+tls| +|`--dtr-external-url`|URL of the host or load balancer clients use to reach DTR. Format https://host[:port]| +|`--dtr-storage-volume`|Full path or volume name to store Docker images in the local filesystem| +|`--nfs-storage-url`|NFS to store Docker images. Requires NFS client libraries. Format nfs:///| +|`--enable-pprof`|Enables pprof profiling of the server| +|`--etcd-heartbeat-interval`|Frequency in milliseconds that the key-value store leader notifies followers| +|`--etcd-election-timeout`|Timeout in milliseconds for key-value store membership| +|`--etcd-snapshot-count`|Number of changes between key-value store snapshots| +|`--ucp-insecure-tls`|Disable TLS verification for UCP| +|`--ucp-ca`|Use a PEM-encoded TLS CA certificate for UCP| +|`--existing-replica-id`|The ID of an existing DTR replica| + diff --git a/datacenter/dtr/2.1/reference/remove.md b/datacenter/dtr/2.1/reference/remove.md new file mode 100644 index 0000000000..393af38cb5 --- /dev/null +++ b/datacenter/dtr/2.1/reference/remove.md @@ -0,0 +1,45 @@ + + +# docker/dtr remove + +Remove a DTR replica + +## Usage + +```bash +docker run -it --rm docker/dtr \ + remove [command options] +``` + +## Description + + +This command removes a replica from a DTR deployment. All DTR containers and +volumes are removed from the node. + + +## Options + +| Option | Description | +|:--------------------------|:---------------------------| +|`--ucp-url`|The UCP URL including domain and port| +|`--ucp-username`|The UCP administrator username| +|`--ucp-password`|The UCP administrator password| +|`--debug`|Enable debug mode for additional logging| +|`--hub-username`|Username to use when pulling images| +|`--hub-password`|Password to use when pulling images| +|`--ucp-insecure-tls`|Disable TLS verification for UCP| +|`--ucp-ca`|Use a PEM-encoded TLS CA certificate for UCP| +|`--force-remove`|Force a DTR replica to be removed| +|`--replica-id`|Assign an ID to the DTR replica. By default the ID is random| +|`--existing-replica-id`|The ID of an existing DTR replica| + diff --git a/datacenter/dtr/2.1/reference/restore.md b/datacenter/dtr/2.1/reference/restore.md new file mode 100644 index 0000000000..f32e670aeb --- /dev/null +++ b/datacenter/dtr/2.1/reference/restore.md @@ -0,0 +1,71 @@ + + +# docker/dtr restore + +Install and restore DTR from an existing backup + +## Usage + +```bash +docker run -i --rm docker/dtr \ + restore [command options] < backup.tar +``` + +## Description + + +This command performs a fresh installation of DTR, and reconfigures it +with configuration data from a tar file generated by the 'backup' command. + +This command does not restore Docker images. You should implement a separate +restore procedure for the Docker images stored in your registry, taking in +consideration whether your DTR installation is configured to store images on +the local filesystem or using a cloud provider. + +After restoring, you can add more DTR replicas by using the the 'join' command. + + +## Options + +| Option | Description | +|:--------------------------|:---------------------------| +|`--ucp-url`|The UCP URL including domain and port| +|`--ucp-username`|The UCP administrator username| +|`--ucp-password`|The UCP administrator password| +|`--debug`|Enable debug mode for additional logging| +|`--hub-username`|Username to use when pulling images| +|`--hub-password`|Password to use when pulling images| +|`--http-proxy`|The HTTP proxy used for outgoing requests| +|`--https-proxy`|The HTTPS proxy used for outgoing requests| +|`--no-proxy`|Don't use a proxy for these domains. Format acme.org[, acme.com]| +|`--replica-http-port`|The public HTTP port for the DTR replica. Default is 80| +|`--replica-https-port`|The public HTTPS port for the DTR replica. Default is 443| +|`--log-protocol`|The protocol for sending container logs: tcp, tcp+tls, udp or internal. Default: internal| +|`--log-host`|Endpoint to send logs to, required if --log-protocol is tcp or udp| +|`--log-level`|Log level for container logs. Default: INFO| +|`--log-tls-ca-cert`|PEM-encoded TLS CA cert for DTR logging driver. Ignored if the logging protocol is not tcp+tls| +|`--log-tls-cert`|PEM-encoded TLS cert for DTR logging driver. Ignored if the logging protocol is not tcp+tls| +|`--log-tls-key`|PEM-encoded TLS key for DTR logging driver. Ignored if the address protocol is not tcp+tls| +|`--log-tls-skip-verify`|Disable TLS verification for the logging service. Ignored if the logging address is not tcp+tls| +|`--dtr-external-url`|URL of the host or load balancer clients use to reach DTR. Format https://host[:port]| +|`--dtr-storage-volume`|Full path or volume name to store Docker images in the local filesystem| +|`--nfs-storage-url`|NFS to store Docker images. Requires NFS client libraries. Format nfs:///| +|`--enable-pprof`|Enables pprof profiling of the server| +|`--etcd-heartbeat-interval`|Frequency in milliseconds that the key-value store leader notifies followers| +|`--etcd-election-timeout`|Timeout in milliseconds for key-value store membership| +|`--etcd-snapshot-count`|Number of changes between key-value store snapshots| +|`--ucp-insecure-tls`|Disable TLS verification for UCP| +|`--ucp-ca`|Use a PEM-encoded TLS CA certificate for UCP| +|`--ucp-node`|The hostname of the node to install DTR| +|`--replica-id`|Assign an ID to the DTR replica. By default the ID is random| +|`--config-only`|Backup/restore only the configurations of DTR and not the database| + diff --git a/datacenter/dtr/2.1/reference/upgrade.md b/datacenter/dtr/2.1/reference/upgrade.md new file mode 100644 index 0000000000..bae2f3e29c --- /dev/null +++ b/datacenter/dtr/2.1/reference/upgrade.md @@ -0,0 +1,42 @@ + + +# docker/dtr upgrade + +Upgrade DTR 2.0.0 or later cluster to this version + +## Usage + +```bash +docker run -it --rm docker/dtr \ + upgrade [command options] +``` + +## Description + + +This command upgrades DTR 2.0.0 or later to the current version of this image. + + +## Options + +| Option | Description | +|:--------------------------|:---------------------------| +|`--ucp-url`|The UCP URL including domain and port| +|`--ucp-username`|The UCP administrator username| +|`--ucp-password`|The UCP administrator password| +|`--debug`|Enable debug mode for additional logging| +|`--hub-username`|Username to use when pulling images| +|`--hub-password`|Password to use when pulling images| +|`--ucp-insecure-tls`|Disable TLS verification for UCP| +|`--ucp-ca`|Use a PEM-encoded TLS CA certificate for UCP| +|`--existing-replica-id`|The ID of an existing DTR replica| + diff --git a/datacenter/dtr/2.1/release-notes/index.md b/datacenter/dtr/2.1/release-notes/index.md new file mode 100644 index 0000000000..751d66d455 --- /dev/null +++ b/datacenter/dtr/2.1/release-notes/index.md @@ -0,0 +1,70 @@ + + +# Docker Trusted Registry release notes + +Here you can learn about new features, bug fixes, breaking changes and +known issues for each DTR version. + +You can then use [the upgrade instructions](../install/upgrade/upgrade-major.md), +to upgrade your installation to the latest release. + +## DTR 2.1 Beta 3 + +(24 Oct 2016) + +**Bug Fixes** + +* Fixed Swift configuration error in DTR web UI when using advanced settings +* Fixed bug where organization owner would not see the delete button for repository +* Changed http response when deleting a non-existent tag from 204 to 404 +* Changed http response when deleting a non-existent manifest from 500 to 404 +* Users now show in the organization member list +* Team name is now being displayed in the UI +* Organization administrators can now delete repositories +* Fixed problem that prevented organization administrators to change a user role +* Fixed problem when removing users from an organization in the UI +* Fixed errors in Internet Explorer 11 +* Fixed problem that caused the garbage collection job to treat valid manifests as corrupt + +## DTR 2.1 Beta 1 + +(7 Oct 2016) + +**docker/dtr image** + +* Added more flags to the docker/dtr image to configure logging and tuning of +etcd when troubleshooting performance issues +* Added support to specify a custom volume or NFS mount to store the Docker images +* Several improvements to make installation command more stable + +**Components** + +* DTR now contains its own Notary server you can use to store secure image metadata +* Notary is highly-available if DTR is configured for high availability + +**UI** + +* Improved UI for configuring garbage collection jobs +* Removed user management pages. User management workflows can be done in UCP +* UI now shows author, push time, and layer sizes for tags + +Additional tag data is available in the API including Tag Author, Time pushed, Layer sizes, and Dockerfile commands. The GUI includes the following tag data: Tag Author, Time pushed, and Layer sizes. + +**General** + +* Added support for S3 compatible storage +* Added support for Google Cloud storage +* Several improvements to garbage collection +* Improved DTR health checking API +* API now returns author, push time, layer size and other information for tags diff --git a/datacenter/dtr/2.1/release-notes/menu.md b/datacenter/dtr/2.1/release-notes/menu.md new file mode 100644 index 0000000000..00da7ae928 --- /dev/null +++ b/datacenter/dtr/2.1/release-notes/menu.md @@ -0,0 +1,12 @@ + diff --git a/datacenter/dtr/2.1/release-notes/prior-release-notes.md b/datacenter/dtr/2.1/release-notes/prior-release-notes.md new file mode 100644 index 0000000000..18b870afdb --- /dev/null +++ b/datacenter/dtr/2.1/release-notes/prior-release-notes.md @@ -0,0 +1,535 @@ + + +# DTR release notes archive + +This document contains the release notes for all versions of Docker Trusted +Registry. + +## Version 2.0.4 + +(13 Oct 2016) + +**General improvements** + +* Increased limits on pagination for all lists in the UI +* Improved health check endpoints to report DTR status more accurately + +**Bug fixes** + +* You can now edit the permissions for a team member +* Fixed issue that prevented DTR from being installed in Docker Engine 1.12 +* Several improvements to the migrate command +* Improved the reconfigure command to allow tuning the key-value store heartbeat +interval, election timeout, and snapshot count +* Users can now pull from public repositories in an organization namespace +without having to authenticate. Requires UCP 1.1.4 + + +## Version 2.0.3 + +August 11, 2016 + +**Bug fixes** + +* You can now add descriptions to the repositories using markdown + +## Version 2.0.2 + +July 6, 2016 + +**docker/dtr image** + +* Added the `docker/dtr images` command that lists all images needed for installing DTR. +* Added the `--extra-envs` flag to the install and join commands, that allows to specify +swarm constraints to the DTR containers. + +**Misc** + +* General improvements to the garbage collection settings screen. +* Deleting a repository is now faster. +* Upgraded the RethinkDB used internally to version 2.3.4, for improved security. +* Upgraded the Nginx used internally to version 1.8.1, for improved security. + +**Bug fixes** + +* Fixed problem that caused the last run time for the garbage collection job to +be wrong. +* When creating users and organizations, the 'Save & create another' button now +works as expected. +* In the Users screen, the organizations each user belongs to is now listed. + +## Version 2.0.1 + +**New features** + +* You can set a maximum duration for the garbage collection job to run. After +this timeout the garbage collection job stops. The job is then resumed on the +next scheduled interval. + +* docker/dtr image + * Added the `docker/dtr upgrade` command, to upgrade an installation. + * Renamed the `--dtr-load-balancer` flag to `--dtr-external-url`. + +**Deprecated features** + +* The user authentication settings page is deprecated and will be removed in a +future release. Configure user authentication in UCP. + +**Bug fixes** + +* UI + * The dropdown filter in the Repositories screen works as expected. + * The global search now returns all results. + * When removing users from an organization, the page now refreshes + automatically. + * When configuring Swift as storage backend, it's now possible to define the + Chunk size option. + * When integrating with LDAP, the 'User search config' section is no longer + being displayed twice. + * When uploading a new license, the page now refreshes automatically. + * On the repository screen, the docker pull command is now displayed + correctly for all users. + +* Users and teams + * When adding users to a team, it's now possible to deselect users. + * When listing users, the organizations those users belong to are displayed + correctly. + * After adding a user to a team, the 'Add user' modal now closes + automatically. + * When adding a user, errors are now displayed correctly. + +* Browsers + * When logging in with Microsoft Edge on Windows 10, users are no longer + redirected indefinitely. + * You can now update DTR license when using Firefox version 45. + * You can now add managed users to teams when using Internet Explorer and + Firefox. + * You can now list repository tags when using Internet Explorer or Firefox. + +* Misc + * The restore command now gives an error when running restore without input + redirection. + * With more than 150k users, the search API is now responsive. + * When UCP and DTR are running on the same host, restarting the host now + restarts DTR containers. For this to work you need to use CS Engine + 1.11.1-cs2 and UCP 1.1.1, or newer versions. + * It's no longer possible to delete the default 'docker-datacenter' + organization. + +**Known issues** + +* UI + * It's not possible to delete tags already deleted by the garbage collection + job. + * On the Users page, the pagination only works until the 20th page. + * The navigation bar doesn't show what page is active. + * After migrating from DTR 1.4.3 some tags are displayed on the UI but cannot + be pulled because they are tags that are not associated with any image. + Contact Docker support for help in removing these tags. + * In the Repository screens, the filter dropdown doesn't reset after + selecting an organization. + +* Misc + * When using Firefox 38.8.0, some buttons are not responsive and tags are not + displayed. As a workaround use a more recent version of Firefox, or a + different browser. + * The docker search command doesn't work with DTR 2.0 and CS Engine 1.10+. + This issue should be fixed on CS Engine 1.12. + * When the DTR proxy container stops, it may seem that the DTR UI is + responding, but it shows an "empty" notification when saving settings. + * When configuring DTR to use a proxy, connections to the Docker Notary server + are routed through the proxy. If the Docker Notary is not reachable through + the proxy, you need to add the Notary server url to the NO_PROXY settings. + +## Version 2.0.0 + +4 May 2016 + +**Features** + +* Core + * Support for high-availability and horizontal scalability. + * UCP and DTR are now using a unified authentication service. + * LDAP configurations should be performed on UCP. In future releases that + configuration will be removed from DTR. + * Users and teams created in the DTR ‘Datacenter’ organization are displayed + in UCP. + * Credentials of LDAP and Active Directory users are no longer stored on disk + Instead a token is used for pushing and pulling images. + * Added anonymous event tracking to allow us to improve DTR. The data is + completely anonymized and you can turn this off in the DTR settings page. +* DTR installer + * The DTR installer is now similar to UCP. + * The DTR installer now runs on a container and has commands to install + configure, and backup DTR. +* UI + * Several changes to the UI to make it consistent with UCP. + +**Bug fixes** + +* Improved search functionality. +* Search autocomplete now displays all users. +* Image tags now take less time to be displayed. + +**Known issues** + +* UI + * The dropdown filter in the Repositories screen doesn't open, but you can + click on the input box. + * The global search is returning a limited number of results. + * When configuring Swift as storage backend, it's not possible to define + the Chunk size option. + * When logging in with Microsoft Edge on Windows 10, users are redirected + indefinitely. + * It's not possible to delete tags already delete by the garbage collector. + * When integrating with LDAP, the 'User search config' section is sometimes + displaying twice. + * On the Users page, the pagination only works until the 20th page. + * When navigating to detail pages, the navigation bar doesn't show what page + is active. + +* Users and teams + * When removing a user from an organization, the page doesn't refresh + automatically. + * When adding users to a team, it's not possible to deselect users. + * When uploading a new license, the page doesn't refresh automatically. + * After adding a user to a team, the 'Add user' modal doesn't close + automatically. + +* API and CLI + * With more than 150k users, the search API takes too long to return a + response. + * The docker search command does not work with DTR 2.0. + * The docker/dtr restore command doesn't return a meaningful error when + invoking the command without redirecting input from a file. + +* Misc + * When using Docker Engine 1.11 and DTR and UCP are running on the same host, + restarting the host might cause the DTR containers not start. This is caused + by a [bug in Docker Engine](https://github.com/docker/docker/issues/22486). + You can restart the DTR containers from the UCP UI. + * When the DTR proxy container stops, it may seem that the DTR UI is + responding but it shows an "empty" notification when saving settings. + * Adding a proxy to the DTR configuration forces the connections to the + notary server to be routed through the proxy. If the notary server is not + reachable through the proxy, add the notary URL to the NO_PROXY setting. + * UCP has a single default organization “docker-datacenter”. If you delete + this organization on DTR, you won’t be able to manage users and teams from + UCP. To recover from this, contact Docker support. + + +## Version 1.4.3 +(22 February 2016) + +The Trusted Registry is supported on SUSE Linux Enterprise 12 OS. + +This release addresses the following issues in Docker Trusted Registry 1.4.2. + +* Improved the Trusted Registry UI response when performing certain operations with a large set of users. + +* Created a new Trusted Registry screen where image tags in a repository are displayed. This fixed the issue where long image tags were truncated in the UI. + +* You can now download the Trusted Registry for offline installation. Refer to the documentation. + +* Corrected an issue where if the Trusted Registry was set to a non default port, users couldn’t push images to it. + +* Improved LDAP configuration. There are now additional user search filters in the Trust Registry UI. The location is Settings > Auth. Select LDAP authentication method. The filters are: + + * `UsernameAttrIsEmail` + * `ScopeOneLevel` + +* Fixed an issue where the Trusted Registry correctly updates team members after an LDAP sync. This removed duplication of users if they were moved to a different team. + +* Previously, if you started the Trusted Registry 1.4.2 with CS Engine 1.7.0 onwards, it might not start because `docker` might start the Trusted Registry containers in an order that makes [links impossible to create](https://github.com/docker/docker/issues/17118). Using CS Engine 1.9 and later with the latest Trusted Registry includes creation of a custom network that allows all containers to connect to each other without links. This means that every time the Trusted Registry starts up, there should be no error. + + Also, when you upgrade CS Engine from 1.6 to 1.9 and the Trusted Registry admin server starts, it checks if it's running with links enabled. If that happens, the Trusted Registry restarts everything, creating the new network if necessary and removing the links, replacing them with a custom "dtr" network. + +* This version deprecates the search API exposed at the /api/v0/index/search +endpoint. Starting on DTR 2.0 this API endpoint will no longer be available. + +* On DTR 2.0 the autocomplete API exposed at the /api/v0/index/autocomplete +endpoint, will start returning a new result structure. + +* On DTR 2.0 all API endpoints that return UserAccess and RepoUserAccess objects +are going to return objects with different properties. + +## Version 1.4.2 +(21 December 2015) + +Release notes contain the following sections: + +* Additional storage backend +* Fixed or updated with this release + +**Additional storage backend** + +This release introduces using Openstack Swift as a storage backend. Refer to the [configuration documentation](../configure/config-storage.md) for details on the Swift driver. + +**Fixed or updated with this release** +This release addresses the following issues in Docker Trusted Registry 1.4.1. + +* Updated the registry from version 2.2.0 to 2.2.1 to ensure that the backend storage Swift driver works correctly. + +* Added a link to the release notes from the Trusted Registry UI Updates page. + +* The Trusted Registry UI now displays a warning message if an administrator had not yet enabled authentication. + +* Corrected an issue where if Trusted Registry administrators were also in a +read-only global team, then they would not see the Trusted Registry admin user +interface. + +* Corrected an issue where uploading an image that took longer than five minutes resulted in an authentication failure. + +* Fixed several issues that caused the Trusted Registry log files to record excessive unnecessary information. + +* Fixed inconsistencies in the garbage collection cron job scheduling between the API and the Trusted Registry UI. This includes: + + * Fixed an issue that if you ran the garbage collection process, the timestamp would not correctly display your last run. + + * Improved the garbage collection cron format. Now a Trusted Registry admin can schedule cron jobs using additional fields such as `@yearly`, `@annually`, `@monthly`, `@weekly`, `@daily`, `@midnight`, and `@hourly`. + + * Fixed an issue where if a Trusted Registry admin did not schedule a garbage collection process, then the Trusted Registry server would log an error. + +## Version 1.4.1 +(24 November 2015) + +**Fixed with this release** +This release addresses the following issues in Docker Trusted Registry 1.4.0. + +* Trusted Registry administrators previously could not pull unlisted repositories in any authorization mode. + +* When using LDAP authentication, only users with lowercase letters, numbers, underscores, periods, and hyphens in their usernames in the LDAP server were +synchronized to the Trusted Registry user database. The Trusted Registry now +synchronizes users with usernames containing uppercase letters. If this affects +your organization, perform a LDAP sync from the Trusted Registry UI. Navigate to +Settings > Auth to perform the sync. + +* Fixed an issue where Trusted Registry administrators could not list all repositories in the registries. To list them, you must use the `catalog` API using a `bash` shell. The following example lists repositories in a Trusted Registry located at my.dtr.host where the user `admin` has password `password`. + + ``` + bash -c 'host=vagrant.host admin=admin password=password token=$(curl -u $admin:$password -k "https://$host/auth/token?service=$host&scope=registry:catalog:*" | python2 -c "import json,sys;obj=json.load(sys.stdin);print obj[\"token\"]") && curl -k -H "Authorization: Bearer $token" "https://$host/v2/_catalog"' + ``` + + +## Version 1.4.3 +(12 November 2015) + +Release notes for the Trusted Registry contain the following sections: + +* New features +* Fixed with this release +* Other corrected issues +* Known issues + +**New features** +This release introduces the following new features. For additional information +on these features, refer to the documentation or when appropriate, the API +documentation. + +* Image deletion and garbage collection + + * You can now delete an image in the registry's image index. This step of marking an unwanted image is called a soft delete. + + * Administrators can use the dashboard or API to configure a task to regularly reclaim the disk space taken up by deleted images. + +* Repositories, Account Management, and interactive API UIs + + * Set up, and manage user accounts, teams, organizations, and repositories from either APIs or through the Trusted Registry user interface. + + * Search, browse, and discover images created by other users through either APIs or through the Trusted Registry UI. + + * Users, depending on their roles, can access account information through the Trusted Registry UI. + + * View new API documentation through the Trusted Registry UI. You can also view this [documentation](/docker-trusted-registry/index.md) from Docker, Inc. docs section. + +* New APIs + + * There are new APIs for accessing repositories, account management, indexing, searching, and reindexing. + + * You can also view an API and using the Swagger UI, click the Try it out button to perform the action. This might be useful, for example, if you need to reindex. + +* Different repository behavior. A repository must first exist before you can push an image to it. This means you must explicitly create (or have it performed for you if you don't have the correct permissions) a repository. This behavior is different than how you would perform this in a free and open-source software registry. + +* New experimental feature. Docker Trusted Registry now integrates with Docker Content Trust using Notary. This is an experimental feature that is available with this release. + +**Fixed with this release** +This release corrects the following issues in Docker Trusted Registry 1.3.3. + +**LDAP Configuration** + +* Performance for LDAP user authentication has been significantly improved, reducing the number of required LDAP requests to only a single BIND request to authenticate a user. + +* The "Read-Write Search Filter" and "Read-Only Search Filter" fields have been deprecated. You can create organization accounts and teams in the Trusted +Registry to allow for more fine grained access control. Team member lists can be +synced with a group in LDAP. + +* The system requires an "Admin Password". Use this password to log in as the +user admin in case the Trusted Registry is unable to authenticate you using +your LDAP server. This account can be used to log in to the Trusted Registry and manage identity and authentication settings. + +* Users on your LDAP server are now synced to the Trusted Registry's local +database using your configured "User Search Filter". Objects in LDAP that match +this filter and have a valid "User Login Attribute" are created as a local +user with the "User Login Attribute" as their username. Only these users are +able to log in to the Trusted Registry. + +* The "Admin LDAP DN" must be specified to identify the group object on your LDAP server. This should be synced to the system administrators list. The +"Admin Group Member Attribute" should be set to the name of the attribute on +this group object which corresponds to the Distinguished Name of the group +member objects. This setting deprecates the old "Admin Search Filter" field. + +**Other corrected issues** + +* Corrected an issue where you could switch from none to managed authentication +without creating an administrator. + +* Added a "rootdirectory" parameter to the S3 storage option. + +**Known issues** + +* Organization owners are unable to delete a repository from the UI. You can still delete a repository through the API and a system administrator can still +delete a repository from the UI. + +* When using LDAP authentication, only users with valid usernames in the LDAP server are synchronized to the Trusted Registry user database. A valid username +only contains lowercase letters, numbers, underscores, periods, hyphens, and +begins and ends with an alphanumeric character. + +* After upgrading to the Trusted Registry 1.4.0, users will not be able to access images from the Trusted Registry if they were previously created without +using namespaces. Docker recommends upgrading to version 1.4.1. After upgrading, +for any repository that was previously pushed to the Trusted Registry, that is +now inaccessible, a Trusted Registry administrator must make it accessible by +the following steps: + + 1. If the repository name is not of the form "namespace/repository", then an administrator must pull all of that repository's tags. For example, you might have an image called `devops_nginx`. The following example shows how you would pull it from a Trusted Registry instance located at my.dtr.host. + + ``` + sudo docker pull --all-tags my.dtr.host/devops_nginx + ``` + + 2. Create a new repository. In the Trusted Registry dashboard, navigate to Repositories > New repository. + + 3. Select the account that you want to associate to that repository, and enter a repository name in that field and save. If you do not see the account name you wanted to use, then create a new organization or user first. For the example `devops_nginx`, you could use `devops` as the organization and `nginx` as the repository name. + + 4. Next, in a `bash` shell, retag all the tags of that repository as seen in the following example: + + ``` + for tag in `sudo docker images | grep my.dtr.host/devops_nginx | awk '{print $2}'` + do sudo docker tag my.dtr.host/devops_nginx:$tag my.dtr.host/devops/nginx:$tag + done + ``` + 5. Push the newly tagged version back to the Trusted Registry as seen in the following example: + + `sudo docker push my.dtr.host/devops/nginx` + + +## Version 1.3.3 +(18 September 2015) (amended: 2 November 2015) + +This release corrects the following issues in Docker Trusted Registry 1.3.2 + +* Fixed an issue related to LDAP integration for users of Oracle Virtual Directory. + +* Corrected an issue where Docker Trusted Registry would not accept a given certificate if the configured domain was only in the Subject Alternative Names +(SANs) field and not in the Common Name (CN) field of the certificate. + +* Docker, Inc. discovered an issue in which the tokens used in authorization caused a break in certain deployments that utilized a load balancer in front of +multiple Trusted Registry instances to achieve high availability. We regret any +inconvenience this may have caused you and is working on a future fix. + +## Version 1.3.2 +(16 September 2015) + +This release addresses the following change in Docker Trusted Registry 1.3.2 and is only available to customers who purchased DTR through Amazon Web Services (AWS) Marketplace. + +* Docker Trusted Registry (DTR) now supports Amazon Web +Services (AWS) Integrated Billing. Previously, AWS users were required to +separately purchase a DTR license from Docker. AWS users can try DTR +out-of-the-box. + +## Version 1.3.1 +(31 August 2015) + +This release corrects the following issues in Docker Trusted Registry 1.3.0 + +* The dashboard page was calculating incorrect stats. +* LDAP group sync failed to handle paginated results for extremely large groups. +* The repo delete endpoint returned incorrect error codes under certain conditions. + +## Version 1.3.0 +(26 August 2015) + +This release addresses a few bugs and issues in Docker Trusted Registry 1.2.0 and introduces some new features and functionality, including: + +* A completely new user-interface for the Admin application brings Docker Trusted Registry in line with other Docker products and provides greater ease-of-use. + +* A new Accounts & Repos API provides new fine-grained role-based access control down to the per-repo level. See the [API's documentation](https://docs.docker.com/apidocs/v1.3.3/) for more information. + +* Improvements to the handling of configuration changes so that fewer restarts are required. + +* Multiple security improvements and bug fixes. + +## Version 1.2.0 +(23 July 2015) + +This release adds CentOS support and addresses a few bugs and issues in Docker Trusted Registry 1.1.0: + +* Fixes an issue where for certain configurations of Docker Trusted Registry, proxy configuration settings and variables were not being passed to all Docker Trusted Registry containers and thus were not being respected. +* Documentation links in the UI now point to correct docs. +* Generated support info bundles have been scrubbed to remove highly sensitive data. +* Certifies support for CentOS 7.1. + +## Version 1.1.0 +(23 June 2015) + +This release of Docker Trusted Registry (formerly DHE) adds major integration +with the AWS and Azure marketplaces, giving customers a smoother installation +path. Docker Trusted Registry 1.1 also adds finer-grained permissions and +improvements and additions to the UI and logging. Bugs in LDAP/AD integration +have also been remediated, improving the stability and usability of Docker +Trusted Registry. See below for specifics. + +**New Features** + +* New, more granular, [roles for users](../user-management/index.md). Docker Trusted Registry users can now be assigned different levels of access +(admin, r/w, r/o) to the repositories. **Important:** Existing Docker Trusted +Registry users should make sure to see the note [below](#dhe-1-0-upgrade-warning) regarding migrating users before upgrading. +* A new storage status indicator for storage space. The dashboard now shows used and available storage space for supported storage drivers. +* A new diagnostics tool gathers and bundles Docker Trusted Registry logs, system information, container +information, and other configuration settings for use by Docker support or as a +backup. +* Performance and reliability improvements to the S3 storage backend. +* Docker Trusted Registry images are now available on the Amazon AWS and Microsoft Azure marketplaces. + +**Fixes** + +The following notable issues have been remediated: + +* Fixed an issue that caused Docker Trusted Registry logins to fail if some LDAP servers were unreachable. +* Fixed a resource leak in Docker Trusted Registry storage. + +**DHE 1.0 Upgrade Warning** + +Customers who are currently using DHE 1.0 **must** follow the [upgrading instructions](https://forums.docker.com/t/upgrading-docker-hub-enterprise-to-docker-trusted-registry/1925) in our support Knowledge Base. These instructions will show you how to modify existing authentication data and storage volume +settings to move to Docker Trusted Registry. Note that automatic upgrading has +been disabled for DHE users because of these issues. + +## Version 1.0.1 +(11 May 2015) + +- Addresses compatibility issue with 1.6.1 CS Docker Engine + +## Version 1.0.0 +(23 Apr 2015) + +- First release diff --git a/datacenter/dtr/2.1/repos-and-images/delete-an-image.md b/datacenter/dtr/2.1/repos-and-images/delete-an-image.md new file mode 100644 index 0000000000..81652a7bc4 --- /dev/null +++ b/datacenter/dtr/2.1/repos-and-images/delete-an-image.md @@ -0,0 +1,26 @@ + + + +# Delete an image + +To delete an image, go to the **DTR web UI**, and navigate to the image +**repository** you want to delete. In the **Tags** tab, select all the image +tags you want to delete, and click the **Delete button**. + +![](../images/delete-an-image-1.png) + +You can also delete all image versions, by deleting the repository. For that, +in the image **repository**, navigate to the **Settings** tab, and click the +**Delete** button. diff --git a/datacenter/dtr/2.1/repos-and-images/index.md b/datacenter/dtr/2.1/repos-and-images/index.md new file mode 100644 index 0000000000..17f03846f5 --- /dev/null +++ b/datacenter/dtr/2.1/repos-and-images/index.md @@ -0,0 +1,105 @@ + + +# Configure your Docker Engine + +By default Docker Engine uses TLS when pushing and pulling images to an +image registry like Docker Trusted Registry. + +If DTR is using the default configurations or was configured to use +self-signed certificates, you need to configure your Docker Engine to trust DTR. +Otherwise, when you try to login or push and pull images to DTR, you'll get an +error: + +```bash +$ docker login + +x509: certificate signed by unknown authority +``` + +The first step to make your Docker Engine trust the certificate authority used +by DTR is to get the DTR CA certificate. Then you configure your operating +system to trust that certificate. + +## Configure your host + +### Ubuntu/ Debian + +```bash +# Download the DTR CA certificate +$ curl -k https:///ca -o /usr/local/share/ca-certificates/.crt +# Refresh the list of certificates to trust +$ sudo update-ca-certificates +# Restart the Docker daemon +$ sudo service docker restart +``` + +### RHEL/ CentOS + +```bash +# Download the DTR CA certificate +$ curl -k https:///ca -o /etc/pki/ca-trust/source/anchors/.crt +# Refresh the list of certificates to trust +$ sudo update-ca-trust +# Restart the Docker daemon +$ sudo /bin/systemctl restart docker.service +``` + +### Boot2Docker + +1. Login into the virtual machine with ssh: + + ```bash + docker-machine ssh + ``` + +2. Create the `bootsync.sh` file, and make it executable: + + ```bash + sudo touch /var/lib/boot2docker/bootsync.sh + sudo chmod 755 /var/lib/boot2docker/bootsync.sh + ``` + +3. Add the following content to the `bootsync.sh` file. You can use nano or vi +for this. + + ```bash + #!/bin/sh + + cat /var/lib/boot2docker/server.pem >> /etc/ssl/certs/ca-certificates.crt + ``` + +4. Add the DTR CA certificate to the `server.pem` file: + + ```bash + curl -k https:///ca | sudo tee -a /var/lib/boot2docker/server.pem + ``` + +5. Run `bootsync.sh` and restart the Docker daemon: + + ```bash + sudo /var/lib/boot2docker/bootsync.sh + sudo /etc/init.d/docker restart + ``` + +## Login into DTR + +To validate that your Docker daemon trusts DTR, trying authenticating against +DTR. + +```bash +$ docker login +``` + +## Where to go next + +* [Pull an image from DTR](pull-an-image.md) diff --git a/datacenter/dtr/2.1/repos-and-images/menu.md b/datacenter/dtr/2.1/repos-and-images/menu.md new file mode 100644 index 0000000000..8093070b5e --- /dev/null +++ b/datacenter/dtr/2.1/repos-and-images/menu.md @@ -0,0 +1,12 @@ + diff --git a/datacenter/dtr/2.1/repos-and-images/pull-an-image.md b/datacenter/dtr/2.1/repos-and-images/pull-an-image.md new file mode 100644 index 0000000000..244831ae8e --- /dev/null +++ b/datacenter/dtr/2.1/repos-and-images/pull-an-image.md @@ -0,0 +1,39 @@ + + +# Pull an image from DTR + +Pulling an image from Docker Trusted Registry is the same as pulling an image +from Docker Hub. Since DTR is secure by default, you always need to authenticate +before pulling images. + +In this example, DTR can be accessed at dtr.company.org, and the user +was granted permissions to access the Java, Python, and Golang repositories. + +![](../images/pull-an-image-1.png) + +Click on the repository to see its details. + +![](../images/pull-an-image-2.png) + +To pull the 1.7 tag of the dave.lauper/golang image, run: + +```bash +$ docker login dtr.company.org +$ docker pull dtr.company.org/dave.lauper/golang:1.7 +``` + +## Where to go next + +* [Push an image to DTR](push-an-image.md) +* [Configure your Docker Engine](index.md) diff --git a/datacenter/dtr/2.1/repos-and-images/push-an-image.md b/datacenter/dtr/2.1/repos-and-images/push-an-image.md new file mode 100644 index 0000000000..37df3cf156 --- /dev/null +++ b/datacenter/dtr/2.1/repos-and-images/push-an-image.md @@ -0,0 +1,79 @@ + + +# Push an image to DTR + +Pushing an image to Docker Trusted Registry is the same as pushing an image +to Docker Hub. +Since DTR is secure by default, you need to create the image repository before +being able to push the image to DTR. + +In this example, we'll create the 'golang' repository in DTR, and push the +Golang 1.7 image to it. + +## Create a repository + +To create a new repository, navigate to the **DTR web application**, and click +the **New repository** button. + +![](../images/push-an-image-1.png) + +Add a **name and description** for the repository, and choose whether your +repository is public or private: + + * Public repositories are visible to all users, but can only be changed by + users granted with permission to write them. + * Private repositories can only be seen by users that have been granted + permissions to that repository. + +![](../images/push-an-image-2.png) + +Click **Save** to create the repository. + +When creating a repository in DTR, the full name of the repository becomes +`//`. In this example, the full +name of our repository will be `dtr.company.org/dave.lauper/golang`. + +## Tag the image + +Before you can push an image to DTR, you need to tag it with the full +repository name. A tag defines where the image was pulled from, and where +it will be pushed to. + +```bash +# Pull from Docker Hub the 1.7 tag of the golang image +$ docker pull golang:1.7 + +# Tag the golang:1.7 image with the full repository name we've created in DTR +$ docker tag golang:1.7 dtr.company.org/dave.lauper/golang:1.7 +``` + +## Push the image + +Now that you have tagged the image, you only need to authenticate and push the +image to DTR. + +```bash +$ docker login dtr.company.org +$ docker push dtr.company.org/dave.lauper/golang:1.7 +``` + +Go back to the **DTR web UI** to validate that the tag was successfully pushed. + +![](../images/push-an-image-3.png) + +## Where to go next + +* [Pull an image from DTR](pull-an-image.md) diff --git a/datacenter/dtr/2.1/support.md b/datacenter/dtr/2.1/support.md new file mode 100644 index 0000000000..69e3952bb2 --- /dev/null +++ b/datacenter/dtr/2.1/support.md @@ -0,0 +1,22 @@ + + +# Get support + +Your Docker Data Center, or Docker Trusted Registry subscription gives you +access to prioritized support. The service levels depend on your subscription. + +If you need help, you can file a ticket via: + +* [Email](mailto:support@docker.com) +* [Docker support page](https://support.docker.com/) + +Be sure to use your company email when filing tickets. diff --git a/datacenter/dtr/2.1/user-management/create-and-manage-orgs.md b/datacenter/dtr/2.1/user-management/create-and-manage-orgs.md new file mode 100644 index 0000000000..07c143ef0e --- /dev/null +++ b/datacenter/dtr/2.1/user-management/create-and-manage-orgs.md @@ -0,0 +1,54 @@ + + +# Create and manage organizations + +When a user creates a repository, only that user has permissions to make changes +to the repository. + +For team workflows, where multiple users have permissions to manage a set of +common repositories, create an organization. By default, DTR has one organization +called 'docker-datacenter', that is shared between DTR and UCP. + +To create a new organization, navigate to the **DTR web UI**, and go to the +**Organizations** page. + +![](../images/create-and-manage-orgs-1.png) + +Click the **New organization** button, and choose a meaningful name for the +organization. + +![](../images/create-and-manage-orgs-2.png) + +Repositories owned by this organization will contain the organization name, so +to pull an image from that repository, you'll use: + +```bash +$ docker pull //: +``` + +Click **Save** to create the organization, and then **click the organization** +to define which users are allowed to manage this +organization. These users will be able to edit the organization settings, edit +all repositories owned by the organization, and define the user permissions for +this organization. + +For this, click the **Add user** button, **select the users** that you want to +grant permissions to manage the organization, and click +**Save**. Then change their permissions from 'Member' to **Admin**. + +![](../images/create-and-manage-orgs-3.png) + +## Where to go next + +* [Create and manage users](create-and-manage-users.md) +* [Create and manage teams](create-and-manage-teams.md) diff --git a/datacenter/dtr/2.1/user-management/create-and-manage-teams.md b/datacenter/dtr/2.1/user-management/create-and-manage-teams.md new file mode 100644 index 0000000000..2fd97342c8 --- /dev/null +++ b/datacenter/dtr/2.1/user-management/create-and-manage-teams.md @@ -0,0 +1,62 @@ + + +# Create and manage teams + +You can extend the user's default permissions by granting them fine-grain +permissions over image repositories. You do this by adding the user to a team. +A team defines the permissions a set of users have for a set of repositories. + +To create a new team, go to the **DTR web UI**, and navigate to the +**Organizations** page. +Then **click the organization** where you want to create the team. In this +example, we'll create the 'billing' team team under the 'whale' organization. + +![](../images/create-and-manage-teams-1.png) + +Click '**+**' to create a new team, and give it a name. + +![](../images/create-and-manage-teams-2.png) + +## Add users to a team + +Once you have created a team, **click the team** name, to manage its settings. +The first thing we need to do is add users to the team. Click the **Add user** +button and add users to the team. + +![](../images/create-and-manage-teams-3.png) + +## Manage team permissions + +The next step is to define the permissions this team has for a set of +repositories. Navigate to the **Repositories** tab, and click the +**Add repository** button. + +![](../images/create-and-manage-teams-4.png) + +Choose the repositories this team has access to, and what permission levels the +team members have. + +![](../images/create-and-manage-teams-5.png) + +There are three permission levels available: + +| Permission level | Description | +|:-----------------|:-----------------------------------------------------------------| +| Read only | View repository and pull images. | +| Read & Write | View repository, pull and push images. | +| Admin | Manage repository and change its settings, pull and push images. | + +## Where to go next + +* [Create and manage users](create-and-manage-users.md) +* [Create and manage organizations](create-and-manage-orgs.md) diff --git a/datacenter/dtr/2.1/user-management/create-and-manage-users.md b/datacenter/dtr/2.1/user-management/create-and-manage-users.md new file mode 100644 index 0000000000..d06bfb323d --- /dev/null +++ b/datacenter/dtr/2.1/user-management/create-and-manage-users.md @@ -0,0 +1,36 @@ + + +# Create and manage users + +When using the Docker Datacenter built-in authentication, you can create users +to grant them fine-grained permissions. +Users are shared across Docker Datacenter. When you create a new user in +Docker Universal Control Plane, that user becomes available in DTR and vice +versa. + +To create a new user, go to the **DTR web UI**, and navigate to the **Users** +page. + +![](../images/create-manage-users-1.png) + +Click the **New user** button, and fill-in the user information. + +![](../images/create-manage-users-2.png) + +Check the **Trusted Registry admin** option, if you want to grant permissions +for the user to change Docker Datacenter configurations. + +## Where to go next + +* [Create and manage organizations](create-and-manage-orgs.md) +* [Create and manage teams](create-and-manage-teams.md) diff --git a/datacenter/dtr/2.1/user-management/index.md b/datacenter/dtr/2.1/user-management/index.md new file mode 100644 index 0000000000..9a4944fd85 --- /dev/null +++ b/datacenter/dtr/2.1/user-management/index.md @@ -0,0 +1,65 @@ + + +# Authentication and authorization + +With DTR you get to control which users have access to your image repositories. + +By default, anonymous users can only pull images from public repositories. +They can't create new repositories or push to existing ones. +You can then grant permissions to enforce fine-grained access control to image +repositories. For that: + +* Start by creating a user. + + Users are shared across Docker Datacenter. When you create a new user in + Docker Universal Control Plane, that user becomes available in DTR and vice + versa. Registered users can create and manage their own repositories. + + You can also integrate with an LDAP service to manage users from a single + place. + +* Extend the permissions by adding the user to a team. + + To extend a user's permission and manage their permissions over repositories, + you add the user to a team. + A team defines the permissions users have for a set of repositories. + + +## Organizations and teams + +When a user creates a repository, only that user can make changes to the +repository settings, and push new images to it. + +Organizations take permission management one step further, since they allow +multiple users to own and manage a common set of repositories. This +is useful when implementing team workflows. With organizations you can +delegate the management of a set of repositories and user permissions to the +organization administrators. + +An organization owns a set of repositories, and defines a set of teams. With +teams you can define fine-grain permissions that a team of +user has for a set of repositories. + +![](../images/authentication-authorization-1.svg) + +In this example, the 'Whale' organization has three repositories and two teams: + +* Members of the blog team can only see and pull images from the whale/java +repository, +* Members of the billing team can manage the whale/golang repository, and push +and pull images from the whale/java repository. + +## Where to go next + +* [Create and manage users](create-and-manage-users.md) diff --git a/datacenter/dtr/2.1/user-management/menu.md b/datacenter/dtr/2.1/user-management/menu.md new file mode 100644 index 0000000000..83efa3de8b --- /dev/null +++ b/datacenter/dtr/2.1/user-management/menu.md @@ -0,0 +1,12 @@ + diff --git a/datacenter/dtr/2.1/user-management/permission-levels.md b/datacenter/dtr/2.1/user-management/permission-levels.md new file mode 100644 index 0000000000..36881a6981 --- /dev/null +++ b/datacenter/dtr/2.1/user-management/permission-levels.md @@ -0,0 +1,62 @@ + + +# Permission levels + +Docker Trusted Registry allows you to define fine-grain permissions over image +repositories. + +## Administrator users + +Users are shared across Docker Datacenter. When you create a new user in Docker +Universal Control Plane, that user becomes available in DTR and vice versa. +When you create an administrator user in DTR, that user is a Docker Datacenter +administrator, with permissions to: + +* Manage users across Docker Datacenter, +* Manage DTR repositories and settings, +* Manage the whole UCP cluster. + +## Team permission levels + +Teams allow you to define the permissions a set of user has for a set of +repositories. Three permission levels are available: + +| Repository operation | read | read-write | admin | +|:----------------------|:----:|:----------:|:-----:| +| View/ browse | x | x | x | +| Pull | x | x | x | +| Push | | x | x | +| Delete tags | | x | x | +| Edit description | | | x | +| Set public or private | | | x | +| Manage user access | | | x | +| Delete repository | | | | + +Team permissions are additive. When a user is a member of multiple teams, they +have the highest permission level defined by those teams. + +## Overall permissions + +Here's an overview of the permission levels available in DTR: + +* Anonymous users: Can search and pull public repositories. +* Users: Can search and pull public repos, and create and manage their own +repositories. +* Team member: Everything a user can do, plus the permissions granted by the teams the user is member of. +* Team admin: Everything a team member can do, and can also add members to the team. +* Organization admin: Everything a team admin can do, can create new teams, and add members to the organization. +* DDC admin: Can manage anything across UCP and DTR. + +## Where to go next + +* [Authentication and authorization](index.md)