github.com/jogo/docker@v1.7.0-rc1/docs/sources/docker-hub-enterprise/quick-start.md (about) 1 page_title: Docker Hub Enterprise: Quick-start: Basic Workflow 2 page_description: Brief tutorial on the basics of Docker Hub Enterprise user workflow 3 page_keywords: docker, documentation, about, technology, understanding, enterprise, hub, registry, image, repository 4 5 6 # Docker Hub Enterprise Quick Start: Basic User Workflow 7 8 ## Overview 9 10 This Quick Start Guide will give you a hands-on look at the basics of using 11 Docker Hub Enterprise (DHE), Docker’s on-premise image storage application. 12 This guide will walk you through using DHE to complete a typical, and critical, 13 part of building a development pipeline: setting up a Jenkins instance. Once you 14 complete the task, you should have a good idea of how DHE works and how it might 15 be useful to you. 16 17 Specifically, this guide demonstrates the process of retrieving the 18 [official Docker image for Jenkins](https://registry.hub.docker.com/_/jenkins/), 19 customizing it to suit your needs, and then hosting it on your private instance 20 of DHE located inside your enterprise’s firewalled environment. Your developers 21 will then be able to retrieve the custom Jenkins image in order to use it to 22 build CI/CD infrastructure for their projects, no matter the platform they’re 23 working from, be it a laptop, a VM, or a cloud provider. 24 25 The guide will walk you through the following steps: 26 27 1. Pulling the official Jenkins image from the public Docker Hub 28 2. Customizing the Jenkins image to suit your needs 29 3. Pushing the customized image to DHE 30 4. Pulling the customized image from DHE 31 4. Launching a container from the custom image 32 5. Using the new Jenkins container 33 34 You should be able to complete this guide in about thirty minutes. 35 36 > **Note:** This guide assumes you have installed a working instance of DHE 37 > reachable at dhe.yourdomain.com. If you need help installing and configuring 38 > DHE, please consult the 39 [installation instructions](./install.md). 40 41 42 ## Pulling the official Jenkins image 43 44 > **Note:** This guide assumes you are familiar with basic Docker concepts such 45 > as images, containers, and registries. If you need to learn more about Docker 46 > fundamentals, please consult the 47 > [Docker user guide](http://docs.docker.com/userguide/). 48 49 First, you will retrieve a copy of the official Jenkins image from the Docker Hub. By default, if 50 Docker can't find an image locally, it will attempt to pull the image from the 51 Docker Hub. From the CLI of a machine running the Docker Engine on your network, use 52 the 53 [`docker pull`](https://docs.docker.com/reference/commandline/cli/#pull) 54 command to pull the public Jenkins image. 55 56 $ docker pull jenkins 57 58 > **Note:** This guide assumes you can run Docker commands from a machine where 59 > you are a member of the `docker` group, or have root privileges. Otherwise, you may 60 > need to add `sudo` to the example commands below. 61 62 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: 63 64 $ docker images 65 REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE 66 jenkins latest 1a7cc22b0ee9 6 days ago 662 MB 67 68 > **Note:** Because the `pull` command did not specify any tags, it will pull 69 > the latest version of the public Jenkins image. If your enterprise environment 70 > requires you to use a specific version, add the tag for the version you need 71 > (e.g., `jenkins:1.565`). 72 73 ## Customizing the Jenkins image 74 75 Now that you have a local copy of the Jenkins image, you’ll customize it so that 76 the containers it builds will integrate with your infrastructure. To do this, 77 you’ll create a custom Docker image that adds a Jenkins plugin that provides 78 fine grained user management. You’ll also configure Jenkins to be more secure by 79 disabling HTTP access and forcing it to use HTTPS. 80 You’ll do this by using a `Dockerfile` and the `docker build` command. 81 82 > **Note:** These are obviously just a couple of examples of the many ways you 83 > can modify and configure Jenkins. Feel free to add or substitute whatever 84 > customization is necessary to run Jenkins in your environment. 85 86 ### Creating a `build` context 87 88 In order to add the new plugin and configure HTTPS access to the custom Jenkins 89 image, you need to: 90 91 1. Create text file that defines the new plugin 92 2. Create copies of the private key and certificate 93 94 All of the above files need to be in the same directory as the Dockerfile you 95 will create in the next step. 96 97 1. Create a build directory called `build`, and change to that new directory: 98 99 $ mkdir build && cd build 100 101 In this directory, create a new file called `plugins` and add the following 102 line: 103 104 role-strategy:2.2.0 105 106 (The plugin version used above was the latest version at the time of writing.) 107 108 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`. 109 110 > **Note:** Because creating new keys varies widely by platform and 111 > implementation, this guide won’t cover key generation. We assume you have 112 > access to existing keys. If you don’t have access, or can’t generate keys 113 > yourself, feel free to skip the steps involving them and HTTPS config. The 114 > guide will still walk you through building a custom Jenkins image and pushing 115 > and pulling that image using DHE. 116 117 ### Creating a Dockerfile 118 119 In the same directory as the `plugins` file and the private key and certificate, 120 create a new [`Dockerfile`](https://docs.docker.com/reference/builder/) with the 121 following contents: 122 123 FROM jenkins 124 125 #New plugins must be placed in the plugins file 126 COPY plugins /usr/share/jenkins/plugins 127 128 #The plugins.sh script will install new plugins 129 RUN /usr/local/bin/plugins.sh /usr/share/jenkins/plugins 130 131 #Copy private key and cert to image 132 COPY https.pem /var/lib/jenkins/cert 133 COPY https.key /var/lib/jenkins/pk 134 135 #Configure HTTP off and HTTPS on, using port 1973 136 ENV JENKINS_OPTS --httpPort=-1 --httpsPort=1973 --httpsCertificate=/var/lib/jenkins/cert --httpsPrivateKey=/var/lib/jenkins/pk 137 138 The first `COPY` instruction in the above will copy the `plugin` file created 139 earlier into the `/usr/share/jenkins` directory within the custom image you are 140 defining with the `Dockerfile`. 141 142 The `RUN` instruction will execute the `/usr/local/bin/plugins.sh` script with 143 the newly copied `plugins` file, which will install the listed plugin. 144 145 The next two `COPY` instructions copy the server’s private key and certificate 146 into the required directories within the new image. 147 148 The `ENV` instruction creates an environment variable called `JENKINS_OPT` in 149 the image you are about to create. This environment variable will be present in 150 any containers launched form the image and contains the required settings to 151 tell Jenkins to disable HTTP and operate over HTTPS. 152 153 > **Note:** You can specify any valid port number as part of the `JENKINS_OPT` 154 > environment variable declared above. The value `1973` used in the example is 155 > arbitrary. 156 157 The `Dockerfile`, the `plugins` file, as well as the private key and 158 certificate, must all be in the same directory because the `docker build` 159 command uses the directory that contains the `Dockerfile` as its “build 160 context”. Only files contained within that “build context” will be included in 161 the image being built. 162 163 ### Building your custom image 164 165 Now that the `Dockerfile`, the `plugins` file, and the files required for HTTPS 166 operation are created in your current working directory, you can build your 167 custom image using the 168 [`docker build` command](https://docs.docker.com/reference/commandline/cli/#build): 169 170 docker build -t dhe.yourdomain.com/ci-infrastructure/jnkns-img . 171 172 > **Note:** Don’t miss the period (`.`) at the end of the command above. This 173 > tells the `docker build` command to use the current working directory as the 174 > "build context". 175 176 This command will build a new Docker image called `jnkns-img` which is based on 177 the public Jenkins image you pulled earlier, but contains all of your 178 customization. 179 180 Please note the use of the `-t` flag in the `docker build` command above. The 181 `-t` flag lets you tag an image so it can be pushed to a custom repository. In 182 the example above, the new image is tagged so it can be pushed to the 183 `ci-infrastructure` Repository within the `dhe.yourdomain.com` registry (your 184 local DHE instance). This will be important when you need to `push` the 185 customized image to DHE later. 186 187 A `docker images` command will now show the custom image alongside the Jenkins 188 image pulled earlier: 189 190 $ sudo docker images 191 REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE 192 dhe.yourdomain.com/ci-infrastructure/jnkns-img latest fc0ab3008d40 2 minutes ago 674.5 MB 193 jenkins latest 1a7cc22b0ee9 6 days ago 662 MB 194 195 ## Pushing to Docker Hub Enterprise 196 197 > **Note**: If your DHE instance has authentication enabled, you will need to 198 > use your command line to `docker login <dhe-hostname>` (e.g., `docker login 199 > dhe.yourdomain.com`). 200 > 201 > Failures due to unauthenticated `docker push` and `docker pull` commands will 202 > look like : 203 > 204 > $ docker pull dhe.yourdomain.com/hello-world 205 > Pulling repository dhe.yourdomain.com/hello-world 206 > FATA[0001] Error: image hello-world:latest not found 207 > 208 > $ docker push dhe.yourdomain.com/hello-world 209 > The push refers to a repository [dhe.yourdomain.com/hello-world] (len: 1) 210 > e45a5af57b00: Image push failed 211 > FATA[0001] Error pushing to registry: token auth attempt for registry 212 > https://dhe.yourdomain.com/v2/: 213 > https://dhe.yourdomain.com/auth/v2/token/ 214 > ?scope=repository%3Ahello-world%3Apull%2Cpush&service=dhe.yourdomain.com 215 > request failed with status: 401 Unauthorized 216 217 Now that you’ve created the custom image, it can be pushed to DHE using the 218 [`docker push`command](https://docs.docker.com/reference/commandline/cli/#push): 219 220 $ docker push dhe.yourdomain.com/ci-infrastructure/jnkns-img 221 511136ea3c5a: Image successfully pushed 222 848d84b4b2ab: Image successfully pushed 223 71d9d77ae89e: Image already exists 224 <truncated ouput...> 225 492ed3875e3e: Image successfully pushed 226 fc0ab3008d40: Image successfully pushed 227 228 You can view the traffic throughput while the custom image is being pushed from 229 the `System Health` tab in DHE: 230 231 ![DHE console push throughput](../assets/console-push.png) 232 233 Once the image is successfully pushed, it can be downloaded, or pulled, by any 234 Docker host that has access to DHE. 235 236 ## Pulling from Docker Hub Enterprise 237 To pull the `jnkns-img` image from DHE, run the 238 [`docker pull`](https://docs.docker.com/reference/commandline/cli/#pull) 239 command from any Docker Host that has access to your DHE instance: 240 241 $ docker pull dhe.yourdomain.com/ci-infrastructure/jnkns-img 242 latest: Pulling from dhe.yourdomain.com/ci-infrastructure/jnkns-img 243 511136ea3c5a: Pull complete 244 848d84b4b2ab: Pull complete 245 71d9d77ae89e: Pull complete 246 <truncated ouput...> 247 492ed3875e3e: Pull complete 248 fc0ab3008d40: Pull complete 249 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. 250 Status: Downloaded newer image for dhe.yourdomain.com/ci-infrastructure/jnkns-img:latest 251 252 You can view the traffic throughput while the custom image is being pulled from 253 the `System Health` tab in DHE: 254 255 ![DHE console pull throughput](../assets/console-pull.png) 256 257 Now that the `jnkns-img` image has been pulled locally from DHE, you can view it 258 in the output of the `docker images` command: 259 260 $ docker images 261 REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE 262 dhe.yourdomain.com/ci-infrastructure/jnkns-img latest fc0ab3008d40 8 minutes ago 674.5 MB 263 264 ## Launching a custom Jenkins container 265 266 Now that you’ve successfully pulled the customized Jenkins image from DHE, you 267 can create a container from it with the 268 [`docker run` command](https://docs.docker.com/reference/commandline/cli/#run): 269 270 271 $ docker run -p 1973:1973 --name jenkins01 dhe.yourdomain.com/ci-infrastructure/jnkns-img 272 /usr/share/jenkins/ref/init.groovy.d/tcp-slave-angent-port.groovy 273 /usr/share/jenkins/ref/init.groovy.d/tcp-slave-angent-port.groovy -> init.groovy.d/tcp-slave-angent-port.groovy 274 copy init.groovy.d/tcp-slave-angent-port.groovy to JENKINS_HOME 275 /usr/share/jenkins/ref/plugins/role-strategy.hpi 276 /usr/share/jenkins/ref/plugins/role-strategy.hpi -> plugins/role-strategy.hpi 277 copy plugins/role-strategy.hpi to JENKINS_HOME 278 /usr/share/jenkins/ref/plugins/dockerhub.hpi 279 /usr/share/jenkins/ref/plugins/dockerhub.hpi -> plugins/dockerhub.hpi 280 copy plugins/dockerhub.hpi to JENKINS_HOME 281 <truncated output...> 282 INFO: Jenkins is fully up and running 283 284 > **Note:** The `docker run` command above maps port 1973 in the container 285 > through to port 1973 on the host. This is the HTTPS port you specified in the 286 > Dockerfile earlier. If you specified a different HTTPS port in your 287 > Dockerfile, you will need to substitute this with the correct port numbers for 288 > your environment. 289 290 You can view the newly launched a container, called `jenkins01`, using the 291 [`docker ps` command](https://docs.docker.com/reference/commandline/cli/#ps): 292 293 $ docker ps 294 CONTAINER ID IMAGE COMMAND CREATED STATUS ...PORTS NAMES 295 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 296 297 298 ## Accessing the new Jenkins container 299 300 The previous `docker run` command mapped port `1973` on the container to port 301 `1973` on the Docker host, so the Jenkins Web UI can be accessed at 302 `https://<docker-host>:1973` (Don’t forget the `s` at the end of `https`.) 303 304 > **Note:** If you are using a self-signed certificate, you may get a security 305 > warning from your browser telling you that the certificate is self-signed and 306 > not trusted. You may wish to add the certificate to the trusted store in order 307 > to prevent further warnings in the future. 308 309 ![Jenkins landing page](../assets/jenkins-ui.png) 310 311 From within the Jenkins Web UI, navigate to `Manage Jenkins` (on the left-hand 312 pane) > `Manage Plugins` > `Installed`. The `Role-based Authorization Strategy` 313 plugin should be present with the `Uninstall` button available to the right. 314 315 ![Jenkins plugin manager](../assets/jenkins-plugins.png) 316 317 In another browser session, try to access Jenkins via the default HTTP port 8080 318 — `http://<docker-host>:8080`. This should result in a “connection timeout,” 319 showing that Jenkins is not available on its default port 8080 over HTTP. 320 321 This demonstration shows your Jenkins image has been configured correctly for 322 HTTPS access, your new plugin was added and is ready for use, and HTTP access 323 has been disabled. At this point, any member of your team can use `docker pull` 324 to access the image from your DHE instance, allowing them to access a 325 configured, secured Jenkins instance that can run on any infrastructure. 326 327 ## Next Steps 328 329 For more information on using DHE, take a look at the 330 [User's Guide](./userguide.md).