Revamps docs for pushing and pulling images

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:

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)

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)

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
 

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
 

repos-and-images/configure-docker-engine.md

@@ -0,0 +1,105 @@
+<!--[metadata]>
++++
+title = "Configure your Docker Engine"
+description = "Learn how to configure your Docker Engine to push and pull images from Docker Trusted Registry."
+keywords = ["docker, registry, TLS, certificates"]
+[menu.main]
+parent="dtr_menu_repos_and_images"
+identifier="dtr_configure_engine"
+weight=0
++++
+<![end-metadata]-->
+
+# 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 <dtr-domain-name>
+
+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://<dtr-domain-name>/ca -o /usr/local/share/ca-certificates/<dtr-domain-name>.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://<dtr-domain-name>/ca -o /etc/pki/ca-trust/source/anchors/<dtr-domain-name>.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 <machine-name>
+    ```
+
+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://<dtr-domain-name>/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 <dtr-domain-name>
+```
+
+## Where to go next
+
+* [Pull an image from DTR](pull-an-image.md)

repos-and-images/create-repo.md

@@ -1,41 +0,0 @@
-<!--[metadata]>
-+++
-aliases = ["/docker-trusted-registry/userguide/"]
-title = "Create a repository"
-description = "Learn how to manage your repositories on Docker Trusted Registry."
-keywords = ["docker, registry, management, repository"]
-[menu.main]
-parent="dtr_menu_repos_and_images"
-identifier="dtr_create_repo"
-weight=0
-+++
-<![end-metadata]-->
-
-## 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)

repos-and-images/delete-an-image.md

@@ -0,0 +1,26 @@
+<!--[metadata]>
++++
+aliases = ["/docker-trusted-registry/soft-garbage/",
+          "/docker-trusted-registry/repos-and-images/delete-images/"]
+title = "Delete an image"
+description = "Learn how to delete images from your repositories on Docker Trusted Registry."
+keywords = ["docker, registry, repository, delete, image"]
+[menu.main]
+parent="dtr_menu_repos_and_images"
+identifier="dtr_delete_images"
+weight=30
++++
+<![end-metadata]-->
+
+
+# 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.

repos-and-images/delete-images.md

@@ -1,128 +0,0 @@
-<!--[metadata]>
-+++
-aliases = ["/docker-trusted-registry/soft-garbage/"]
-title = "Delete images"
-description = "Learn how to delete images from your repositories on Docker Trusted Registry."
-keywords = ["docker, registry, management, repository, delete, image"]
-[menu.main]
-parent="dtr_menu_repos_and_images"
-identifier="dtr_delete_images"
-weight=20
-+++
-<![end-metadata]-->
-
-
-# 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 <username>:<password> -X DELETE https://<DTR HOST>/api/v0/repositories/<namespace>/<reponame>/manifests/<reference>
-```
-
-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 <username>:<password> -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 <username>:<password> -H 'Content-Type: application/json' -X POST https://<DTR
-HOST>/api/v0/admin/settings/registry/garbageCollection/schedule -d '{"schedule":
-"<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 <username>:<password> https://<DTR
-HOST>/api/v0/admin/settings/registry/garbageCollection/lastSavings
-```
-
-The results are also displayed in the Trusted Registry UI by navigating to Settings > Garbage collection.

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)

repos-and-images/pull-an-image.md

@@ -0,0 +1,38 @@
+<!--[metadata]>
++++
+title = "Pull an image"
+description = "Learn how to pull an image from Docker Trusted Registry."
+keywords = ["docker, registry, images, pull"]
+[menu.main]
+parent="dtr_menu_repos_and_images"
+identifier="dtr_pull_image"
+weight=10
++++
+<![end-metadata]-->
+
+# 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)

repos-and-images/push-an-image.md

@@ -0,0 +1,79 @@
+<!--[metadata]>
++++
+aliases = ["/docker-trusted-registry/repos-and-images/create-repo/",
+          "/docker-trusted-registry/userguide/",
+          "/docker-trusted-registry/repos-and-images/push-and-pull-images/"]
+title = "Push an image"
+description = "Learn how to push an image to Docker Trusted Registry."
+keywords = ["docker, registry, images, pull"]
+[menu.main]
+parent="dtr_menu_repos_and_images"
+identifier="dtr_push_image"
+weight=20
++++
+<![end-metadata]-->
+
+# 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
+`<dtr-domain-name>/<user-or-org>/<repository-name>`. 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)

repos-and-images/push-and-pull-images.md

@@ -1,119 +0,0 @@
-<!--[metadata]>
-+++
-title = "Push and pull images"
-description = "Learn how to push and pull images from your repositories on Docker Trusted Registry."
-keywords = ["docker, registry, management, repository"]
-[menu.main]
-parent="dtr_menu_repos_and_images"
-identifier="dtr_push_pull_images"
-weight=10
-+++
-<![end-metadata]-->
-
-## 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 <dtr-hostname>` (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
-```