diff --git a/configure/configuration.md b/configure/configuration.md index 099113780d..e7e23cec1e 100644 --- a/configure/configuration.md +++ b/configure/configuration.md @@ -21,9 +21,7 @@ view configuration options. Configuring is grouped by the following: * [Storage settings](config-storage.md) * [License](../install/license.md) * [Authentication settings](config-auth.md) (including LDAP) -* [Garbage collection](../repos-and-images/delete-images.md) * Updates -* Docker daemon (this is set from the Trusted Registry CLI and not the UI) Saving changes you've made to settings will restart various services, as follows: diff --git a/images/accounts-long-tag.png b/images/accounts-long-tag.png deleted file mode 100644 index a80b2bfcf7..0000000000 Binary files a/images/accounts-long-tag.png and /dev/null differ diff --git a/images/create-repo-1.png b/images/create-repo-1.png deleted file mode 100644 index 4461b31307..0000000000 Binary files a/images/create-repo-1.png and /dev/null differ diff --git a/images/create-repo-2.png b/images/create-repo-2.png deleted file mode 100644 index 1df62b53d9..0000000000 Binary files a/images/create-repo-2.png and /dev/null differ diff --git a/images/delete-an-image-1.png b/images/delete-an-image-1.png new file mode 100644 index 0000000000..beff50eefc Binary files /dev/null and b/images/delete-an-image-1.png differ diff --git a/images/gc1.png b/images/gc1.png deleted file mode 100644 index 2db3446ceb..0000000000 Binary files a/images/gc1.png and /dev/null differ diff --git a/images/gc3.png b/images/gc3.png deleted file mode 100644 index 1832e7f667..0000000000 Binary files a/images/gc3.png and /dev/null differ diff --git a/images/long-tag.png b/images/long-tag.png deleted file mode 100644 index 56ce79c83c..0000000000 Binary files a/images/long-tag.png and /dev/null differ diff --git a/images/pull-an-image-1.png b/images/pull-an-image-1.png new file mode 100644 index 0000000000..b95124da2b Binary files /dev/null and b/images/pull-an-image-1.png differ diff --git a/images/pull-an-image-2.png b/images/pull-an-image-2.png new file mode 100644 index 0000000000..d9e91bc86b Binary files /dev/null and b/images/pull-an-image-2.png differ diff --git a/images/push-an-image-1.png b/images/push-an-image-1.png new file mode 100644 index 0000000000..ce53a90d17 Binary files /dev/null and b/images/push-an-image-1.png differ diff --git a/images/push-an-image-2.png b/images/push-an-image-2.png new file mode 100644 index 0000000000..6ec8ae7463 Binary files /dev/null and b/images/push-an-image-2.png differ diff --git a/images/push-an-image-3.png b/images/push-an-image-3.png new file mode 100644 index 0000000000..65e6e8b14d Binary files /dev/null and b/images/push-an-image-3.png differ diff --git a/images/tag-removal.png b/images/tag-removal.png deleted file mode 100644 index da91154ccc..0000000000 Binary files a/images/tag-removal.png and /dev/null differ diff --git a/index.md b/index.md index 58a5b3ac99..afb990d2b0 100644 --- a/index.md +++ b/index.md @@ -26,5 +26,5 @@ The DTR documentation includes the following topics: * [Monitor and troubleshoot](monitor-troubleshoot/monitor.md) * [High-availability](high-availability/high-availability.md) * [User management](user-management/permission-levels.md) -* [Repositories and images](repos-and-images/create-repo.md) +* [Repositories and images](repos-and-images/configure-docker-engine.md) * [Release notes](release-notes/release-notes.md) diff --git a/install/index.md b/install/index.md index 241cb5f206..075168440d 100644 --- a/install/index.md +++ b/install/index.md @@ -18,5 +18,5 @@ This section includes the following topics: * [Install Docker Trusted Registry](install-dtr.md) * [Install offline](install-dtr-offline.md) * [License DTR](license.md) -* [Upgrade to DTR 2.0](upgrade/upgrade-major.md) +* [Upgrade DTR](upgrade/upgrade-minor.md) * [Uninstall](uninstall.md) diff --git a/install/install-dtr.md b/install/install-dtr.md index ab9d6240c9..bc39899445 100644 --- a/install/install-dtr.md +++ b/install/install-dtr.md @@ -103,7 +103,7 @@ After installing DTR, you should configure: 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/push-and-pull-images.md). +[Learn how to push and pull images](../repos-and-images/configure-docker-engine.md). ## Step 6. Join replicas to the cluster diff --git a/install/upgrade/upgrade-major.md b/install/upgrade/upgrade-major.md index 6e3baf8b8c..0b5f9a5aab 100644 --- a/install/upgrade/upgrade-major.md +++ b/install/upgrade/upgrade-major.md @@ -99,7 +99,7 @@ You can find the certificates of DTR 1.4.3 under `/usr/local/etc/dtr/ssl`. 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/push-and-pull-images.md). +[Learn how to push and pull images](../../repos-and-images/configure-docker-engine.md). ## Step 6. Join replicas to your cluster diff --git a/repos-and-images/configure-docker-engine.md b/repos-and-images/configure-docker-engine.md new file mode 100644 index 0000000000..17f03846f5 --- /dev/null +++ b/repos-and-images/configure-docker-engine.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/repos-and-images/create-repo.md b/repos-and-images/create-repo.md deleted file mode 100644 index 8c22ef6db1..0000000000 --- a/repos-and-images/create-repo.md +++ /dev/null @@ -1,41 +0,0 @@ - - -## Create a repository - -Before you can push images to your Docker Trusted Registry, you need to -create a repository for them. - -To create a new repository, navigate to the **DTR web application**, and click -the **New repository** button. - -![](../images/create-repo-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/create-repo-2.png) - -Click **Save** to create the repository. Now you can push your images to this -repository. - - -## Where to go next - -* [Push and pull images](push-and-pull-images.md) -* [Delete images](delete-images.md) diff --git a/repos-and-images/delete-an-image.md b/repos-and-images/delete-an-image.md new file mode 100644 index 0000000000..81652a7bc4 --- /dev/null +++ b/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/repos-and-images/delete-images.md b/repos-and-images/delete-images.md deleted file mode 100644 index 77e5f75f87..0000000000 --- a/repos-and-images/delete-images.md +++ /dev/null @@ -1,128 +0,0 @@ - - - -# Delete images - -This document describes the two-step process of removing an image from the -Trusted Registry. This process is first performed by developers wanting to -remove their images and marking them for deletion. Then, an administrator -removes those images mainly through a recurring garbage collection job. - -## Understand the role of images and manifests in image deletion - -Manifests are a type of file that describe images. They reference a list of -layers and hold metadata about the described image. Manifests can also share -layers. Tags, which are labels applied to images, point to manifests. You can -reference an image by tag or directly by the hash of the manifest. If you -purposefully delete one of those manifests and the image layers referenced by -that manifest become orphaned, then they can be removed during the garbage -collection job. In the following diagram, _both_ manifests point to the first layer, #2543d8. - -![](../images/gc1.png) - -Since many developers may use a base image for future images, it is possible -that there will be image layers that will never be deleted. There might be other -manifests that point to layers of the base image which could still be used by -others as seen in the second diagram. - -![](../images/gc3.png) - -## Prerequisites -You need an image to remove. - -## Soft delete an image - -Developers may want to remove an image for several reasons. -Examples include: - -* The image is outdated and there is a new version. -* The image is no longer used. - -If a developer removes the manifest of an image, then it is called a soft -deletion. Developers won't be able to access that image, although physically, it -it still in the repository. - -You can perform a soft deletion, either from the UI or from the command line. - -From the Trusted Registry dashboard, navigate to Repositories > Tags. Click the trash can next to the images you want to remove. They are now marked for the garbage collection job. - -![](../images/tag-removal.png) - - -If you prefer to not use the UI, then you can open a Trusted Registry command line and type: - -```bash -$ curl -u : -X DELETE https:///api/v0/repositories///manifests/ -``` - -You can only delete one image at a time and you must also be authenticated as a -user who has "write" level access to the repository. - -## Set up garbage collection - -Trusted Registry administrators can optimize registry storage and free up space. -They do this by setting up a recurring garbage collection job (cron job) where -the system searches for any layers that are not referenced by any manifests and -removes them. Administrators can perform this garbage collection process -immediately, or more realistically, on a periodic automatic schedule. -They perform garbage collection of unreferenced layers tags either -through a Trusted Registry CLI or through the Trusted Registry UI. - -If administrators choose to have the garbage collection process performed -immediately, they can type in a Trusted Registry CLI: - - curl -X POST -u : -H "Content-Type: application/json" "https://api/v0/admin/jobs" -d "{ \"job\" : \"registryGC\"}" - -However, it is more common to set up the garbage collection cron job to be performed routinely as seen in the following example: - -```bash -$ curl -u : -H 'Content-Type: application/json' -X POST https:///api/v0/admin/settings/registry/garbageCollection/schedule -d '{"schedule": -""}' -``` - -Trusted Registry administrators can also set the cron job through the Trusted -Registry UI. Navigate to Settings > Garbage collection to schedule a job. - -### A cron job example -A Trusted Registry cron format has **at most** four fields representing hour, -day, month, and day of week respectively. Moreover, administrators can use the -following shortcuts: `@yearly`, `@annually`, `@monthly`, `@weekly`, `@daily`, -`@midnight`, `@hourly` in either the UI or through the Trusted Registry CLI. If -administrators choose to use the shortcuts, then only one can be used. - -An example schedule of nightly at midnight would be: `0 * * *`. Or alternately, -for the same schedule, you could enter: @midnight. You can also enter less than -four parameters if that's all the job requires. - -See the [package cron page](https://godoc.org/github.com/robfig/cron) for other -examples depending on your company's requirements. - ->**Note**: The prior link displays examples using more than four fields. When Trusted Registry administrators set up a cron schedule, they are limited to only the four fields representing hour, day, month, and day of week. - -Your downtime depends on the number of images and/or layers that are to be -deleted. Docker recommends performing garbage collection weekly during off time. -While garbage collection is occurring, anyone who tries to push an image will -get an error message. - -## View your garbage collection results - -See your results by running the following example in a Trusted Registry CLI: - -```bash -$ curl -u : https:///api/v0/admin/settings/registry/garbageCollection/lastSavings -``` - -The results are also displayed in the Trusted Registry UI by navigating to Settings > Garbage collection. diff --git a/repos-and-images/index.md b/repos-and-images/index.md index 6a519279d2..c1a2d42a8d 100644 --- a/repos-and-images/index.md +++ b/repos-and-images/index.md @@ -14,6 +14,7 @@ weight=90 This section includes the following topics: -* [Create a repository](create-repo.md) -* [Push and pull images](push-and-pull-images.md) -* [Delete images](delete-images.md) +* [Configure your Docker Engine](configure-docker-engine.md) +* [Pull an image](pull-an-image.md) +* [Push an image](push-an-image.md) +* [Delete an image](delete-an-image.md) diff --git a/repos-and-images/pull-an-image.md b/repos-and-images/pull-an-image.md new file mode 100644 index 0000000000..705859dbba --- /dev/null +++ b/repos-and-images/pull-an-image.md @@ -0,0 +1,38 @@ + + +# 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](configure-docker-engine.md) diff --git a/repos-and-images/push-an-image.md b/repos-and-images/push-an-image.md new file mode 100644 index 0000000000..37df3cf156 --- /dev/null +++ b/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/repos-and-images/push-and-pull-images.md b/repos-and-images/push-and-pull-images.md deleted file mode 100644 index 32ce7800a2..0000000000 --- a/repos-and-images/push-and-pull-images.md +++ /dev/null @@ -1,119 +0,0 @@ - - -## Push and pull overview - -One of your main activities you do in the Trusted Registry, is to push and pull -images to and from the Trusted Registry image storage service. For example, you -might pull an official image for Ubuntu from the Docker Hub, customize it with -configuration settings for your infrastructure, and then push it to your Docker -Trusted Registry image storage for other developers to pull and use for their -development environments. - -Pushing and pulling images with Trusted Registry works similarly like any other -Docker registry. You use the `docker pull` command to retrieve images and the -`docker push` command to add an image. - -> **Note**: If your Docker Trusted Registry instance has authentication enabled, you will need to ->use your command line to `docker login ` (for example `docker login -> dtr.yourdomain.com`). -> -> Failures due to unauthenticated `docker push` and `docker pull` commands -> look like: -> -> $ docker pull dtr.yourdomain.com/hello-world -> Pulling repository dtr.yourdomain.com/hello-world -> FATA[0001] Error: image hello-world:latest not found -> -> $ docker push dtr.yourdomain.com/hello-world -> The push refers to a repository [dtr.yourdomain.com/hello-world] (len: 1) -> e45a5af57b00: Image push failed -> FATA[0001] Error pushing to registry: token auth attempt for registry -> https://dtr.yourdomain.com/v2/: -> https://dtr.yourdomain.com/auth/v2/token/?scope= -> repository%3Ahello-world%3Apull%2Cpush&service=dtr.yourdomain.com -> request failed with status: 401 Unauthorized - -## Push images - -You push an image up to a Docker Trusted Registry repository by using the -[`docker push` command](/engine/reference/commandline/push.md). - -You can add a `tag` to your image so that you can more easily identify it -among other variants and so that it refers to your Docker Trusted Registry server. - - $ docker tag hello-world:latest dtr.yourdomain.com/yourusername/hello-mine:latest - -The command labels a `hello-world:latest` image using a new tag in the -`[REGISTRYHOST/][USERNAME/]NAME[:TAG]` format. The `REGISTRYHOST` in this -case is your Docker Trusted Registry server, `dtr.yourdomain.com`, and the `USERNAME` is -`yourusername`. Lastly, the image tag is set to `hello-mine:latest`. - -Once an image is tagged, you can push it to Docker Trusted Registry with: - - $ docker push dtr.yourdomain.com/yourusername/hello-mine:latest - -> **Note**: If the Docker daemon on which you are running `docker push` doesn't -> have the right certificates set up, you get an error similar to: -> -> $ docker push dtr.yourdomain.com/demouser/hello-world -> FATA[0000] Error response from daemon: v1 ping attempt failed with error: -> Get https://dtr.yourdomain.com/v1/_ping: x509: certificate signed by -> unknown authority. If this private registry supports only HTTP or HTTPS -> with an unknown CA certificate, please add `--insecure-registry -> dtr.yourdomain.com` to the daemon's arguments. In the case of HTTPS, if -> you have access to the registry's CA certificate, no need for the flag; -> simply place the CA certificate at -> /etc/docker/certs.d/dtr.yourdomain.com/ca.crt - -[Learn how to configure Docker Engine to fix this](../configure/config-security.md) - -## Pull images - -You can retrieve an image with the -[`docker pull` command](/engine/reference/commandline/run.md), -or you can retrieve an image and run Docker to build the container with the -[`docker run`command](/engine/reference/commandline/run.md). - -To retrieve an image from the Trusted Registry and then run Docker to build the -container, add -the needed info to `docker run`: - -```bash -$ docker run dtr.yourdomain.com/yourusername/hello-mine - -latest: Pulling from dtr.yourdomain.com/yourusername/hello-mine -511136ea3c5a: Pull complete -31cbccb51277: Pull complete -e45a5af57b00: Already exists -Digest: sha256:45f0de377f861694517a1440c74aa32eecc3295ea803261d62f950b1b757bed1 -Status: Downloaded newer image for dtr.yourdomain.com/demouser/hello-mine:latest -``` - -If you don't specify a version, by default the `latest` version of an -image is pulled. - -If you run `docker images` after this, then you see a `hello-mine` image. - -```bash -$ docker images -REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE -dtr.yourdomain.com/yourusername/hello-mine latest e45a5af57b00 3 months ago 910 B -``` - - -To pull an image without building the container, use `docker pull` and specify -your Docker Trusted Registry by adding it to the command: - -```bash -$ docker pull dtr.yourdomain.com/yourusername/hello-mine -```