page_title: Docker Hub Enterprise: Quick-start: Basic Workflow page_description: Brief tutorial on the basics of Docker Hub Enterprise user workflow page_keywords: docker, documentation, about, technology, understanding, enterprise, hub, registry, image, repository # Docker Hub Enterprise Quick Start: Basic User Workflow ## Overview This Quick Start Guide will give you a hands-on look at the basics of using Docker Hub Enterprise (DHE), Docker’s on-premise image storage application. This guide will walk you through using DHE to complete a typical, and critical, part of building a development pipeline: setting up a Jenkins instance. Once you complete the task, you should have a good idea of how DHE works and how it might be useful to you. Specifically, this guide demonstrates the process of retrieving the [official Docker image for Jenkins](https://registry.hub.docker.com/_/jenkins/), customizing it to suit your needs, and then hosting it on your private instance of DHE located inside your enterprise’s firewalled environment. Your developers will then be able to retrieve the custom Jenkins image in order to use it to build CI/CD infrastructure for their projects, no matter the platform they’re working from, be it a laptop, a VM, or a cloud provider. The guide will walk you through the following steps: 1. Pulling the official Jenkins image from the public Docker Hub 2. Customizing the Jenkins image to suit your needs 3. Pushing the customized image to DHE 4. Pulling the customized image from DHE 4. Launching a container from the custom image 5. Using the new Jenkins container You should be able to complete this guide in about thirty minutes. > **Note:** This guide assumes you have installed a working instance of DHE > reachable at dhe.yourdomain.com. If you need help installing and configuring > DHE, please consult the [installation instructions](./install.md). ## Pulling the official Jenkins image > **Note:** This guide assumes you are familiar with basic Docker concepts such > as images, containers, and registries. If you need to learn more about Docker > fundamentals, please consult the > [Docker user guide](http://docs.docker.com/userguide/). First, you will retrieve a copy of the official Jenkins image from the Docker Hub. By default, if Docker can't find an image locally, it will attempt to pull the image from the Docker Hub. From the CLI of a machine running the Docker Engine on your network, use the [`docker pull`](https://docs.docker.com/reference/commandline/cli/#pull) command to pull the public Jenkins image. $ docker pull jenkins > **Note:** This guide assumes you can run Docker commands from a machine where > you are a member of the `docker` group, or have root privileges. Otherwise, you may > need to add `sudo` to the example commands below. Docker will start the process of pulling the image from the Hub. Once it has completed, the Jenkins image should be visible in the output of a [`docker images`](https://docs.docker.com/reference/commandline/cli/#images) command, which lists your available images: $ docker images REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE jenkins latest 1a7cc22b0ee9 6 days ago 662 MB > **Note:** Because the `pull` command did not specify any tags, it will pull > the latest version of the public Jenkins image. If your enterprise environment > requires you to use a specific version, add the tag for the version you need > (e.g., `jenkins:1.565`). ## Customizing the Jenkins image Now that you have a local copy of the Jenkins image, you’ll customize it so that the containers it builds will integrate with your infrastructure. To do this, you’ll create a custom Docker image that adds a Jenkins plugin that provides fine grained user management. You’ll also configure Jenkins to be more secure by disabling HTTP access and forcing it to use HTTPS. You’ll do this by using a `Dockerfile` and the `docker build` command. > **Note:** These are obviously just a couple of examples of the many ways you > can modify and configure Jenkins. Feel free to add or substitute whatever > customization is necessary to run Jenkins in your environment. ### Creating a `build` context In order to add the new plugin and configure HTTPS access to the custom Jenkins image, you need to: 1. Create text file that defines the new plugin 2. Create copies of the private key and certificate All of the above files need to be in the same directory as the Dockerfile you will create in the next step. 1. Create a build directory called `build`, and change to that new directory: $ mkdir build && cd build In this directory, create a new file called `plugins` and add the following line: role-strategy:2.2.0 (The plugin version used above was the latest version at the time of writing.) 2. You will also need to make copies of the server’s private key and certificate. Give the copies the following names — `https.key` and `https.pem`. > **Note:** Because creating new keys varies widely by platform and > implementation, this guide won’t cover key generation. We assume you have > access to existing keys. If you don’t have access, or can’t generate keys > yourself, feel free to skip the steps involving them and HTTPS config. The > guide will still walk you through building a custom Jenkins image and pushing > and pulling that image using DHE. ### Creating a Dockerfile In the same directory as the `plugins` file and the private key and certificate, create a new [`Dockerfile`](https://docs.docker.com/reference/builder/) with the following contents: FROM jenkins #New plugins must be placed in the plugins file COPY plugins /usr/share/jenkins/plugins #The plugins.sh script will install new plugins RUN /usr/local/bin/plugins.sh /usr/share/jenkins/plugins #Copy private key and cert to image COPY https.pem /var/lib/jenkins/cert COPY https.key /var/lib/jenkins/pk #Configure HTTP off and HTTPS on, using port 1973 ENV JENKINS_OPTS --httpPort=-1 --httpsPort=1973 --httpsCertificate=/var/lib/jenkins/cert --httpsPrivateKey=/var/lib/jenkins/pk The first `COPY` instruction in the above will copy the `plugin` file created earlier into the `/usr/share/jenkins` directory within the custom image you are defining with the `Dockerfile`. The `RUN` instruction will execute the `/usr/local/bin/plugins.sh` script with the newly copied `plugins` file, which will install the listed plugin. The next two `COPY` instructions copy the server’s private key and certificate into the required directories within the new image. The `ENV` instruction creates an environment variable called `JENKINS_OPT` in the image you are about to create. This environment variable will be present in any containers launched form the image and contains the required settings to tell Jenkins to disable HTTP and operate over HTTPS. > **Note:** You can specify any valid port number as part of the `JENKINS_OPT` > environment variable declared above. The value `1973` used in the example is > arbitrary. The `Dockerfile`, the `plugins` file, as well as the private key and certificate, must all be in the same directory because the `docker build` command uses the directory that contains the `Dockerfile` as its “build context”. Only files contained within that “build context” will be included in the image being built. ### Building your custom image Now that the `Dockerfile`, the `plugins` file, and the files required for HTTPS operation are created in your current working directory, you can build your custom image using the [`docker build` command](https://docs.docker.com/reference/commandline/cli/#build): docker build -t dhe.yourdomain.com/ci-infrastructure/jnkns-img . > **Note:** Don’t miss the period (`.`) at the end of the command above. This > tells the `docker build` command to use the current working directory as the > "build context". This command will build a new Docker image called `jnkns-img` which is based on the public Jenkins image you pulled earlier, but contains all of your customization. Please note the use of the `-t` flag in the `docker build` command above. The `-t` flag lets you tag an image so it can be pushed to a custom repository. In the example above, the new image is tagged so it can be pushed to the `ci-infrastructure` Repository within the `dhe.yourdomain.com` registry (your local DHE instance). This will be important when you need to `push` the customized image to DHE later. A `docker images` command will now show the custom image alongside the Jenkins image pulled earlier: $ sudo docker images REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE dhe.yourdomain.com/ci-infrastructure/jnkns-img latest fc0ab3008d40 2 minutes ago 674.5 MB jenkins latest 1a7cc22b0ee9 6 days ago 662 MB ## Pushing to Docker Hub Enterprise > **Note**: If your DHE instance has authentication enabled, you will need to > use your command line to `docker login ` (e.g., `docker login > dhe.yourdomain.com`). > > Failures due to unauthenticated `docker push` and `docker pull` commands will > look like : > > $ docker pull dhe.yourdomain.com/hello-world > Pulling repository dhe.yourdomain.com/hello-world > FATA[0001] Error: image hello-world:latest not found > > $ docker push dhe.yourdomain.com/hello-world > The push refers to a repository [dhe.yourdomain.com/hello-world] (len: 1) > e45a5af57b00: Image push failed > FATA[0001] Error pushing to registry: token auth attempt for registry > https://dhe.yourdomain.com/v2/: > https://dhe.yourdomain.com/auth/v2/token/ > ?scope=repository%3Ahello-world%3Apull%2Cpush&service=dhe.yourdomain.com > request failed with status: 401 Unauthorized Now that you’ve created the custom image, it can be pushed to DHE using the [`docker push`command](https://docs.docker.com/reference/commandline/cli/#push): $ docker push dhe.yourdomain.com/ci-infrastructure/jnkns-img 511136ea3c5a: Image successfully pushed 848d84b4b2ab: Image successfully pushed 71d9d77ae89e: Image already exists 492ed3875e3e: Image successfully pushed fc0ab3008d40: Image successfully pushed You can view the traffic throughput while the custom image is being pushed from the `System Health` tab in DHE: ![DHE console push throughput](../assets/console-push.png) Once the image is successfully pushed, it can be downloaded, or pulled, by any Docker host that has access to DHE. ## Pulling from Docker Hub Enterprise To pull the `jnkns-img` image from DHE, run the [`docker pull`](https://docs.docker.com/reference/commandline/cli/#pull) command from any Docker Host that has access to your DHE instance: $ docker pull dhe.yourdomain.com/ci-infrastructure/jnkns-img latest: Pulling from dhe.yourdomain.com/ci-infrastructure/jnkns-img 511136ea3c5a: Pull complete 848d84b4b2ab: Pull complete 71d9d77ae89e: Pull complete 492ed3875e3e: Pull complete fc0ab3008d40: Pull complete dhe.yourdomain.com/ci-infrastructure/jnkns-img:latest: The image you are pulling has been verified. Important: image verification is a tech preview feature and should not be relied on to provide security. Status: Downloaded newer image for dhe.yourdomain.com/ci-infrastructure/jnkns-img:latest You can view the traffic throughput while the custom image is being pulled from the `System Health` tab in DHE: ![DHE console pull throughput](../assets/console-pull.png) Now that the `jnkns-img` image has been pulled locally from DHE, you can view it in the output of the `docker images` command: $ docker images REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE dhe.yourdomain.com/ci-infrastructure/jnkns-img latest fc0ab3008d40 8 minutes ago 674.5 MB ## Launching a custom Jenkins container Now that you’ve successfully pulled the customized Jenkins image from DHE, you can create a container from it with the [`docker run` command](https://docs.docker.com/reference/commandline/cli/#run): $ docker run -p 1973:1973 --name jenkins01 dhe.yourdomain.com/ci-infrastructure/jnkns-img /usr/share/jenkins/ref/init.groovy.d/tcp-slave-angent-port.groovy /usr/share/jenkins/ref/init.groovy.d/tcp-slave-angent-port.groovy -> init.groovy.d/tcp-slave-angent-port.groovy copy init.groovy.d/tcp-slave-angent-port.groovy to JENKINS_HOME /usr/share/jenkins/ref/plugins/role-strategy.hpi /usr/share/jenkins/ref/plugins/role-strategy.hpi -> plugins/role-strategy.hpi copy plugins/role-strategy.hpi to JENKINS_HOME /usr/share/jenkins/ref/plugins/dockerhub.hpi /usr/share/jenkins/ref/plugins/dockerhub.hpi -> plugins/dockerhub.hpi copy plugins/dockerhub.hpi to JENKINS_HOME INFO: Jenkins is fully up and running > **Note:** The `docker run` command above maps port 1973 in the container > through to port 1973 on the host. This is the HTTPS port you specified in the > Dockerfile earlier. If you specified a different HTTPS port in your > Dockerfile, you will need to substitute this with the correct port numbers for > your environment. You can view the newly launched a container, called `jenkins01`, using the [`docker ps` command](https://docs.docker.com/reference/commandline/cli/#ps): $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS ...PORTS NAMES 2e5d2f068504 dhe.yourdomain.com/ci-infrastructure/jnkns-img:latest "/usr/local/bin/jenk About a minute ago Up About a minute 50000/tcp, 0.0.0.0:1973->1973/tcp jenkins01 ## Accessing the new Jenkins container The previous `docker run` command mapped port `1973` on the container to port `1973` on the Docker host, so the Jenkins Web UI can be accessed at `https://:1973` (Don’t forget the `s` at the end of `https`.) > **Note:** If you are using a self-signed certificate, you may get a security > warning from your browser telling you that the certificate is self-signed and > not trusted. You may wish to add the certificate to the trusted store in order > to prevent further warnings in the future. ![Jenkins landing page](../assets/jenkins-ui.png) From within the Jenkins Web UI, navigate to `Manage Jenkins` (on the left-hand pane) > `Manage Plugins` > `Installed`. The `Role-based Authorization Strategy` plugin should be present with the `Uninstall` button available to the right. ![Jenkins plugin manager](../assets/jenkins-plugins.png) In another browser session, try to access Jenkins via the default HTTP port 8080 — `http://:8080`. This should result in a “connection timeout,” showing that Jenkins is not available on its default port 8080 over HTTP. This demonstration shows your Jenkins image has been configured correctly for HTTPS access, your new plugin was added and is ready for use, and HTTP access has been disabled. At this point, any member of your team can use `docker pull` to access the image from your DHE instance, allowing them to access a configured, secured Jenkins instance that can run on any infrastructure. ## Next Steps For more information on using DHE, take a look at the [User's Guide](./userguide.md).