github.com/jogo/docker@v1.7.0-rc1/docs/sources/docker-hub-enterprise/install.md (about) 1 page_title: Docker Hub Enterprise: Install 2 page_description: Installation instructions for Docker Hub Enterprise 3 page_keywords: docker, documentation, about, technology, understanding, enterprise, hub, registry 4 5 # Installing Docker Hub Enterprise 6 7 ## Overview 8 9 This document describes the process of obtaining, installing, and securing 10 Docker Hub Enterprise (DHE). DHE is installed from Docker containers. Once 11 installed, you will need to select a method of securing it. This doc will 12 explain the options you have for security and help you find the resources needed 13 to configure it according to your chosen method. More configuration details can 14 be found in the [DHE Configuration page](./configuration.md). 15 16 Specifically, installation requires completion of these steps, in order: 17 18 1. Acquire a license by purchasing DHE or requesting a trial license. 19 2. Install the commercially supported Docker Engine. 20 3. Install DHE 21 4. Add your license to your DHE instance 22 23 ## Licensing 24 25 In order to run DHE, you will need to acquire a license, either by purchasing 26 DHE or requesting a trial license. The license will be associated with your 27 Docker Hub account or Docker Hub organization (so if you don't have an account, 28 you'll need to set one up, which can be done at the same time as your license 29 request). To get your license or start your trial, please contact our 30 [sales department](mailto:sales@docker.com). Upon completion of your purchase or 31 request, you will receive an email with further instructions for licensing your 32 copy of DHE. 33 34 ## Prerequisites 35 36 DHE 1.0.1 requires the following: 37 38 * Commercially supported Docker Engine 1.6.1 or later running on an 39 Ubuntu 14.04 LTS, RHEL 7.1 or RHEL 7.0 host. (See below for instructions on how 40 to install the commercially supported Docker Engine.) 41 42 > **Note:** In order to remain in compliance with your DHE support agreement, 43 > you must use the current version of commercially supported Docker Engine. 44 > Running the regular, open source version of Engine is **not** supported. 45 46 * Your Docker daemon needs to be listening to the Unix socket (the default) so 47 that it can be bind-mounted into the DHE management containers, allowing 48 DHE to manage itself and its updates. For this reason, your DHE host will also 49 need internet connectivity so it can access the updates. 50 51 * Your host also needs to have TCP ports `80` and `443` available for the DHE 52 container port mapping. 53 54 * You will also need the Docker Hub user-name and password used when obtaining 55 the DHE license (or the user-name of an administrator of the Hub organization 56 that obtained an Enterprise license). 57 58 ## Installing the Commercially Supported Docker Engine 59 60 Since DHE is installed using Docker, the commercially supported Docker Engine 61 must be installed first. This is done with an RPM or DEB repository, which you 62 set up using a Bash script downloaded from the [Docker Hub](https://hub.docker.com). 63 64 ### Download the commercially supported Docker Engine installation script 65 66 To download the commercially supported Docker Engine Bash installation script, 67 log in to the [Docker Hub](https://hub.docker.com) with the user-name used to 68 obtain your license . Once you're logged in, go to the 69 ["Enterprise Licenses"](https://registry.hub.docker.com/account/licenses/) page 70 in your Hub account's "Settings" section. 71 72 Select your intended host operating system from the "Download CS Engine" drop- 73 down at the top right of the page and then, once the Bash setup script is 74 downloaded, follow the steps below appropriate for your chosen OS. 75 76 ![Docker Hub Docker engine install dropdown](../assets/docker-hub-org-enterprise-license-CSDE-dropdown.png) 77 78 ### RHEL 7.0/7.1 installation 79 80 First, copy the downloaded Bash setup script to your RHEL host. Next, run the 81 following to install commercially supported Docker Engine and its dependencies, 82 and then start the Docker daemon: 83 84 ``` 85 $ sudo yum update && sudo yum upgrade 86 $ chmod 755 docker-cs-engine-rpm.sh 87 $ sudo ./docker-cs-engine-rpm.sh 88 $ sudo yum install docker-engine-cs 89 $ sudo systemctl enable docker.service 90 $ sudo systemctl start docker.service 91 ``` 92 93 In order to simplify using Docker, you can get non-sudo access to the Docker 94 socket by adding your user to the `docker` group, then logging out and back in 95 again: 96 97 ``` 98 $ sudo usermod -a -G docker $USER 99 $ exit 100 ``` 101 102 > **Note**: you may need to reboot your server to update its RHEL kernel. 103 104 ### Ubuntu 14.04 LTS installation 105 106 First, copy the downloaded Bash setup script to your Ubuntu host. Next, run the 107 following to install commercially supported Docker Engine and its dependencies: 108 109 ``` 110 $ sudo apt-get update && sudo apt-get upgrade 111 $ chmod 755 docker-cs-engine-deb.sh 112 $ sudo ./docker-cs-engine-deb.sh 113 $ sudo apt-get install docker-engine-cs 114 ``` 115 Lastly, confirm Docker is running with `sudo service docker start`. 116 117 In order to simplify using Docker, you can get non-sudo access to the Docker 118 socket by adding your user to the `docker` group, then logging out and back in 119 again: 120 121 ``` 122 $ sudo usermod -a -G docker $USER 123 $ exit 124 ``` 125 126 > **Note**: you may need to reboot your server to update its LTS kernel. 127 128 ## Upgrading the Commercially Supported Docker Engine 129 130 CS Docker Engine 1.6.1 contains fixes to security vulnerabilities, 131 and customers should upgrade to it immediately. 132 133 > **Note**: If you have CS Docker Engine 1.6.0 installed, it must be upgraded; 134 however, due to compatibility issues, [DHE must be upgraded](#upgrading-docker-hub-enterprise) 135 first. 136 137 The CS Docker Engine installation script set up the RHEL/Ubuntu package repositories, 138 so upgrading the Engine only requires you to run the update commands on your server. 139 140 ### RHEL 7.0/7.1 upgrade 141 142 To upgrade CS Docker Engine, run the following command: 143 144 ``` 145 $ sudo yum update 146 $ sudo systemctl daemon-reload && sudo systemctl restart docker 147 ``` 148 149 ### Ubuntu 14.04 LTS upgrade 150 151 To upgrade CS Docker Engine, run the following command: 152 153 ``` 154 $ sudo apt-get update && sudo apt-get dist-upgrade docker-engine-cs 155 ``` 156 157 ## Installing Docker Hub Enterprise 158 159 Once the commercially supported Docker Engine is installed, you can install DHE 160 itself. DHE is a self-installing application built and distributed using Docker 161 and the [Docker Hub](https://registry.hub.docker.com/). It is able to restart 162 and reconfigure itself using the Docker socket that is bind-mounted to its 163 container. 164 165 Start installing DHE by running the "dockerhubenterprise/manager" container: 166 167 ``` 168 $ sudo bash -c "$(sudo docker run dockerhubenterprise/manager install)" 169 ``` 170 171 > **Note**: `sudo` is needed for `dockerhubenterprise/manager` commands to 172 > ensure that the Bash script is run with full access to the Docker host. 173 174 You can also find this command on the "Enterprise Licenses" section of your Hub 175 user profile. The command will execute a shell script that creates the needed 176 directories and then runs Docker to pull DHE's images and run its containers. 177 178 Depending on your internet connection, this process may take several minutes to 179 complete. 180 181 A successful installation will pull a large number of Docker images and should 182 display output similar to: 183 184 ``` 185 $ sudo bash -c "$(sudo docker run dockerhubenterprise/manager install)" 186 Unable to find image 'dockerhubenterprise/manager:latest' locally 187 Pulling repository dockerhubenterprise/manager 188 c46d58daad7d: Pulling image (latest) from dockerhubenterprise/manager 189 c46d58daad7d: Pulling image (latest) from dockerhubenterprise/manager 190 c46d58daad7d: Pulling dependent layers 191 511136ea3c5a: Download complete 192 fa4fd76b09ce: Pulling metadata 193 fa4fd76b09ce: Pulling fs layer 194 ff2996b1faed: Download complete 195 ... 196 fd7612809d57: Pulling metadata 197 fd7612809d57: Pulling fs layer 198 fd7612809d57: Download complete 199 c46d58daad7d: Pulling metadata 200 c46d58daad7d: Pulling fs layer 201 c46d58daad7d: Download complete 202 c46d58daad7d: Download complete 203 Status: Downloaded newer image for dockerhubenterprise/manager:latest 204 Unable to find image 'dockerhubenterprise/manager:1.0.0_8ce62a61e058' locally 205 Pulling repository dockerhubenterprise/manager 206 c46d58daad7d: Download complete 207 511136ea3c5a: Download complete 208 fa4fd76b09ce: Download complete 209 1c8294cc5160: Download complete 210 117ee323aaa9: Download complete 211 2d24f826cb16: Download complete 212 33bfc1956932: Download complete 213 48f0dd6c9414: Download complete 214 65c30f72ecb2: Download complete 215 d4b29764d0d3: Download complete 216 5654f4fe5384: Download complete 217 9b9faa6ecd11: Download complete 218 0c275f56ca5c: Download complete 219 ff2996b1faed: Download complete 220 fd7612809d57: Download complete 221 Status: Image is up to date for dockerhubenterprise/manager:1.0.0_8ce62a61e058 222 INFO [1.0.0_8ce62a61e058] Attempting to connect to docker engine dockerHost="unix:///var/run/docker.sock" 223 INFO [1.0.0_8ce62a61e058] Running install command 224 <...output truncated...> 225 Creating container docker_hub_enterprise_load_balancer with docker daemon unix:///var/run/docker.sock 226 Starting container docker_hub_enterprise_load_balancer with docker daemon unix:///var/run/docker.sock 227 Bringing up docker_hub_enterprise_log_aggregator. 228 Creating container docker_hub_enterprise_log_aggregator with docker daemon unix:///var/run/docker.sock 229 Starting container docker_hub_enterprise_log_aggregator with docker daemon unix:///var/run/docker.sock 230 $ docker ps 231 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 232 0168f37b6221 dockerhubenterprise/log-aggregator:1.0.0_8ce62a61e058 "log-aggregator" 4 seconds ago Up 4 seconds docker_hub_enterprise_log_aggregator 233 b51c73bebe8b dockerhubenterprise/nginx:1.0.0_8ce62a61e058 "nginxWatcher" 4 seconds ago Up 4 seconds 0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp docker_hub_enterprise_load_balancer 234 e8327864356b dockerhubenterprise/admin-server:1.0.0_8ce62a61e058 "server" 5 seconds ago Up 5 seconds 80/tcp docker_hub_enterprise_admin_server 235 52885a6e830a dockerhubenterprise/auth_server:alpha-a5a2af8a555e "garant --authorizat 6 seconds ago Up 5 seconds 8080/tcp 236 ``` 237 238 Once this process completes, you should be able to manage and configure your DHE 239 instance by pointing your browser to `https://<host-ip>/`. 240 241 Your browser will warn you that this is an unsafe site, with a self-signed, 242 untrusted certificate. This is normal and expected; allow this connection 243 temporarily. 244 245 ### Setting the DHE Domain Name 246 247 The DHE Administrator site will also warn that the "Domain Name" is not set. Go 248 to the "Settings" tab, and set the "Domain Name" to the full host-name of your 249 DHE server. 250 Hitting the "Save and Restart DHE Server" button will generate a new certificate, which will be used 251 by both the DHE Administrator web interface and the DHE Registry server. 252 253 After the server restarts, you will again need to allow the connection to the untrusted DHE web admin site. 254 255 ![http settings page</admin/settings#http>](../assets/admin-settings-http-unlicensed.png) 256 257 Lastly, you will see a warning notifying you that this instance of DHE is 258 unlicensed. You'll correct this in the next step. 259 260 ### Add your license 261 262 The DHE registry services will not start until you add your license. 263 To do that, you'll first download your license from the Docker Hub and then 264 upload it to your DHE web admin server. Follow these steps: 265 266 1. If needed, log back into the [Docker Hub](https://hub.docker.com) 267 using the user-name you used when obtaining your license. Go to "Settings" (in 268 the menu under your user-name, top right) to get to your account settings, and 269 then click on "Enterprise Licenses" in the side bar at left. 270 271 2. You'll see a list of available licenses. Click on the download button to 272 obtain the license file you'd like to use. 273 ![Download DHE license](../assets/docker-hub-org-enterprise-license.png) 274 275 3. Next, go to your DHE instance in your browser and click on the Settings tab 276 and then the "License" tab. Click on the "Upload license file" button, which 277 will open a standard file browser. Locate and select the license file you 278 downloaded in step 2, above. Approve the selection to close the dialog. 279 ![http settings page</admin/settings#license>](../assets/admin-settings-license.png) 280 281 4. Click the "Save and Restart DHE" button, which will quit DHE and then restart it, registering 282 the new license. 283 284 5. Verify the acceptance of the license by confirming that the "unlicensed copy" 285 warning is no longer present. 286 287 ### Securing DHE 288 289 Securing DHE is **required**. You will not be able to push or pull from DHE until you secure it. 290 291 There are several options and methods for securing DHE. For more information, 292 see the [configuration documentation](./configuration.md#security) 293 294 ### Using DHE to push and pull images 295 296 Now that you have DHE configured with a "Domain Name" and have your client 297 Docker daemons configured with the required security settings, you can test your 298 setup by following the instructions for 299 [Using DHE to Push and pull images](./userguide.md#using-dhe-to-push-and-pull-images). 300 301 ### DHE web interface and registry authentication 302 303 By default, there is no authentication set on either the DHE web admin 304 interface or the DHE registry. You can restrict access using an in-DHE 305 configured set of users (and passwords), or you can configure DHE to use LDAP- 306 based authentication. 307 308 See [DHE Authentication settings](./configuration.md#authentication) for more 309 details. 310 311 ## Upgrading Docker Hub Enterprise 312 313 DHE has been designed to allow on-the-fly software upgrades. Start by 314 clicking on the "System Health" tab. In the upper, right-hand side of the 315 dashboard, below the navigation bar, you'll see the currently installed version 316 (e.g., `Current Version: 0.1.12345`). 317 318 If your DHE instance is the latest available, you will also see the message: 319 "System Up to Date." 320 321 If there is an upgrade available, you will see the message "System Update 322 Available!" alongside a button labeled "Update to Version X.XX". To upgrade, DHE 323 will pull new DHE container images from the Docker Hub. If you have not already 324 connected to Docker Hub, DHE will prompt you to log in. 325 326 The upgrade process requires a small amount of downtime to complete. To complete 327 the upgrade, DHE will: 328 * Connect to the Docker Hub to pull new container images with the new version of 329 DHE. 330 * Deploy those containers 331 * Shut down the old containers 332 * Resolve any necessary links/urls. 333 334 Assuming you have a decent internet connection, the entire upgrade process 335 should complete within a few minutes. 336 337 You should now [upgrade CS Docker Engine](#upgrading-the-commercially-supported-docker-engine). 338 339 > **Note**: If Docker engine is upgraded first (DHE 1.0.0 on CS Docker Engine 1.6.1), 340 > DHE can still be upgraded from the command line by running: 341 > 342 > `sudo bash -c "$(sudo docker run dockerhubenterprise/manager:1.0.0 upgrade 1.0.1)"` 343 344 ## Next Steps 345 346 For information on configuring DHE for your environment, take a look at the 347 [Configuration instructions](./configuration.md). 348