github.com/fcwu/docker@v1.4.2-0.20150115145920-2a69ca89f0df/docs/sources/userguide/dockerlinks.md (about) 1 page_title: Linking Containers Together 2 page_description: Learn how to connect Docker containers together. 3 page_keywords: Examples, Usage, user guide, links, linking, docker, documentation, examples, names, name, container naming, port, map, network port, network 4 5 # Linking Containers Together 6 7 In [the Using Docker section](/userguide/usingdocker), you saw how you can 8 connect to a service running inside a Docker container via a network 9 port. But a port connection is only one way you can interact with services and 10 applications running inside Docker containers. In this section, we'll briefly revisit 11 connecting via a network port and then we'll introduce you to another method of access: 12 container linking. 13 14 ## Network port mapping refresher 15 16 In [the Using Docker section](/userguide/usingdocker), you created a 17 container that ran a Python Flask application: 18 19 $ sudo docker run -d -P training/webapp python app.py 20 21 > **Note:** 22 > Containers have an internal network and an IP address 23 > (as we saw when we used the `docker inspect` command to show the container's 24 > IP address in the [Using Docker](/userguide/usingdocker/) section). 25 > Docker can have a variety of network configurations. You can see more 26 > information on Docker networking [here](/articles/networking/). 27 28 When that container was created, the `-P` flag was used to automatically map any 29 network ports inside it to a random high port from the range 49153 30 to 65535 on our Docker host. Next, when `docker ps` was run, you saw that 31 port 5000 in the container was bound to port 49155 on the host. 32 33 $ sudo docker ps nostalgic_morse 34 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 35 bc533791f3f5 training/webapp:latest python app.py 5 seconds ago Up 2 seconds 0.0.0.0:49155->5000/tcp nostalgic_morse 36 37 You also saw how you can bind a container's ports to a specific port using 38 the `-p` flag: 39 40 $ sudo docker run -d -p 5000:5000 training/webapp python app.py 41 42 And you saw why this isn't such a great idea because it constrains you to 43 only one container on that specific port. 44 45 There are also a few other ways you can configure the `-p` flag. By 46 default the `-p` flag will bind the specified port to all interfaces on 47 the host machine. But you can also specify a binding to a specific 48 interface, for example only to the `localhost`. 49 50 $ sudo docker run -d -p 127.0.0.1:5000:5000 training/webapp python app.py 51 52 This would bind port 5000 inside the container to port 5000 on the 53 `localhost` or `127.0.0.1` interface on the host machine. 54 55 Or, to bind port 5000 of the container to a dynamic port but only on the 56 `localhost`, you could use: 57 58 $ sudo docker run -d -p 127.0.0.1::5000 training/webapp python app.py 59 60 You can also bind UDP ports by adding a trailing `/udp`. For example: 61 62 $ sudo docker run -d -p 127.0.0.1:5000:5000/udp training/webapp python app.py 63 64 You also learned about the useful `docker port` shortcut which showed us the 65 current port bindings. This is also useful for showing you specific port 66 configurations. For example, if you've bound the container port to the 67 `localhost` on the host machine, then the `docker port` output will reflect that. 68 69 $ sudo docker port nostalgic_morse 5000 70 127.0.0.1:49155 71 72 > **Note:** 73 > The `-p` flag can be used multiple times to configure multiple ports. 74 75 ## Docker Container Linking 76 77 Network port mappings are not the only way Docker containers can connect 78 to one another. Docker also has a linking system that allows you to link 79 multiple containers together and send connection information from one to another. 80 When containers are linked, information about a source container can be sent to a 81 recipient container. This allows the recipient to see selected data describing 82 aspects of the source container. 83 84 ## Container naming 85 86 To establish links, Docker relies on the names of your containers. 87 You've already seen that each container you create has an automatically 88 created name; indeed you've become familiar with our old friend 89 `nostalgic_morse` during this guide. You can also name containers 90 yourself. This naming provides two useful functions: 91 92 1. It can be useful to name containers that do specific functions in a way 93 that makes it easier for you to remember them, for example naming a 94 container containing a web application `web`. 95 96 2. It provides Docker with a reference point that allows it to refer to other 97 containers, for example, you can specify to link the container `web` to container `db`. 98 99 You can name your container by using the `--name` flag, for example: 100 101 $ sudo docker run -d -P --name web training/webapp python app.py 102 103 This launches a new container and uses the `--name` flag to 104 name the container `web`. You can see the container's name using the 105 `docker ps` command. 106 107 $ sudo docker ps -l 108 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 109 aed84ee21bde training/webapp:latest python app.py 12 hours ago Up 2 seconds 0.0.0.0:49154->5000/tcp web 110 111 You can also use `docker inspect` to return the container's name. 112 113 $ sudo docker inspect -f "{{ .Name }}" aed84ee21bde 114 /web 115 116 > **Note:** 117 > Container names have to be unique. That means you can only call 118 > one container `web`. If you want to re-use a container name you must delete 119 > the old container (with `docker rm`) before you can create a new 120 > container with the same name. As an alternative you can use the `--rm` 121 > flag with the `docker run` command. This will delete the container 122 > immediately after it is stopped. 123 124 ## Container Linking 125 126 Links allow containers to discover each other and securely transfer information about one 127 container to another container. When you set up a link, you create a conduit between a 128 source container and a recipient container. The recipient can then access select data 129 about the source. To create a link, you use the `--link` flag. First, create a new 130 container, this time one containing a database. 131 132 $ sudo docker run -d --name db training/postgres 133 134 This creates a new container called `db` from the `training/postgres` 135 image, which contains a PostgreSQL database. 136 137 Now, you need to delete the `web` container you created previously so you can replace it 138 with a linked one: 139 140 $ sudo docker rm -f web 141 142 Now, create a new `web` container and link it with your `db` container. 143 144 $ sudo docker run -d -P --name web --link db:db training/webapp python app.py 145 146 This will link the new `web` container with the `db` container you created 147 earlier. The `--link` flag takes the form: 148 149 --link name:alias 150 151 Where `name` is the name of the container we're linking to and `alias` is an 152 alias for the link name. You'll see how that alias gets used shortly. 153 154 Next, inspect your linked containers with `docker inspect`: 155 156 $ sudo docker inspect -f "{{ .HostConfig.Links }}" web 157 [/db:/web/db] 158 159 You can see that the `web` container is now linked to the `db` container 160 `web/db`. Which allows it to access information about the `db` container. 161 162 So what does linking the containers actually do? You've learned that a link allows a 163 source container to provide information about itself to a recipient container. In 164 our example, the recipient, `web`, can access information about the source `db`. To do 165 this, Docker creates a secure tunnel between the containers that doesn't need to 166 expose any ports externally on the container; you'll note when we started the 167 `db` container we did not use either the `-P` or `-p` flags. That's a big benefit of 168 linking: we don't need to expose the source container, here the PostgreSQL database, to 169 the network. 170 171 Docker exposes connectivity information for the source container to the 172 recipient container in two ways: 173 174 * Environment variables, 175 * Updating the `/etc/hosts` file. 176 177 ### Environment Variables 178 179 When two containers are linked, Docker will set some environment variables 180 in the target container to enable programmatic discovery of information 181 related to the source container. 182 183 First, Docker will set an `<alias>_NAME` environment variable specifying the 184 alias of each target container that was given in a `--link` parameter. So, 185 for example, if a new container called `web` is being linked to a database 186 container called `db` via `--link db:webdb` then in the `web` container 187 would be `WEBDB_NAME=/web/webdb`. 188 189 Docker will then also define a set of environment variables for each 190 port that is exposed by the source container. The pattern followed is: 191 192 * `<name>_PORT_<port>_<protocol>` will contain a URL reference to the 193 port. Where `<name>` is the alias name specified in the `--link` parameter 194 (e.g. `webdb`), `<port>` is the port number being exposed, and `<protocol>` 195 is either `TCP` or `UDP`. The format of the URL will be: 196 `<protocol>://<container_ip_address>:<port>` 197 (e.g. `tcp://172.17.0.82:8080`). This URL will then be 198 split into the following 3 environment variables for convenience: 199 * `<name>_PORT_<port>_<protocol>_ADDR` will contain just the IP address 200 from the URL (e.g. `WEBDB_PORT_8080_TCP_ADDR=172.17.0.82`). 201 * `<name>_PORT_<port>_<protocol>_PORT` will contain just the port number 202 from the URL (e.g. `WEBDB_PORT_8080_TCP_PORT=8080`). 203 * `<name>_PORT_<port>_<protocol>_PROTO` will contain just the protocol 204 from the URL (e.g. `WEBDB_PORT_8080_TCP_PROTO=tcp`). 205 206 If there are multiple ports exposed then the above set of environment 207 variables will be defined for each one. 208 209 Finally, there will be an environment variable called `<alias>_PORT` that will 210 contain the URL of the first exposed port of the source container. 211 For example, `WEBDB_PORT=tcp://172.17.0.82:8080`. In this case, 'first' 212 is defined as the lowest numbered port that is exposed. If that port is 213 used for both tcp and udp, then the tcp one will be specified. 214 215 Returning back to our database example, you can run the `env` 216 command to list the specified container's environment variables. 217 218 ``` 219 $ sudo docker run --rm --name web2 --link db:db training/webapp env 220 . . . 221 DB_NAME=/web2/db 222 DB_PORT=tcp://172.17.0.5:5432 223 DB_PORT_5432_TCP=tcp://172.17.0.5:5432 224 DB_PORT_5432_TCP_PROTO=tcp 225 DB_PORT_5432_TCP_PORT=5432 226 DB_PORT_5432_TCP_ADDR=172.17.0.5 227 . . . 228 ``` 229 230 > **Note**: 231 > These Environment variables are only set for the first process in the 232 > container. Similarly, some daemons (such as `sshd`) 233 > will scrub them when spawning shells for connection. 234 235 You can see that Docker has created a series of environment variables with 236 useful information about the source `db` container. Each variable is prefixed with 237 `DB_`, which is populated from the `alias` you specified above. If the `alias` 238 were `db1`, the variables would be prefixed with `DB1_`. You can use these 239 environment variables to configure your applications to connect to the database 240 on the `db` container. The connection will be secure and private; only the 241 linked `web` container will be able to talk to the `db` container. 242 243 ### Updating the `/etc/hosts` file 244 245 In addition to the environment variables, Docker adds a host entry for the 246 source container to the `/etc/hosts` file. Here's an entry for the `web` 247 container: 248 249 $ sudo docker run -t -i --rm --link db:db training/webapp /bin/bash 250 root@aed84ee21bde:/opt/webapp# cat /etc/hosts 251 172.17.0.7 aed84ee21bde 252 . . . 253 172.17.0.5 db 254 255 You can see two relevant host entries. The first is an entry for the `web` 256 container that uses the Container ID as a host name. The second entry uses the 257 link alias to reference the IP address of the `db` container. You can ping 258 that host now via this host name. 259 260 root@aed84ee21bde:/opt/webapp# apt-get install -yqq inetutils-ping 261 root@aed84ee21bde:/opt/webapp# ping db 262 PING db (172.17.0.5): 48 data bytes 263 56 bytes from 172.17.0.5: icmp_seq=0 ttl=64 time=0.267 ms 264 56 bytes from 172.17.0.5: icmp_seq=1 ttl=64 time=0.250 ms 265 56 bytes from 172.17.0.5: icmp_seq=2 ttl=64 time=0.256 ms 266 267 > **Note:** 268 > In the example, you'll note you had to install `ping` because it was not included 269 > in the container initially. 270 271 Here, you used the `ping` command to ping the `db` container using its host entry, 272 which resolves to `172.17.0.5`. You can use this host entry to configure an application 273 to make use of your `db` container. 274 275 > **Note:** 276 > You can link multiple recipient containers to a single source. For 277 > example, you could have multiple (differently named) web containers attached to your 278 >`db` container. 279 280 If you restart the source container, the linked containers `/etc/hosts` files 281 will be automatically updated with the source container's new IP address, 282 allowing linked communication to continue. 283 284 $ sudo docker restart db 285 root@aed84ee21bde:/opt/webapp# cat /etc/hosts 286 172.17.0.7 aed84ee21bde 287 . . . 288 172.17.0.9 db 289 290 # Next step 291 292 Now that you know how to link Docker containers together, the next step is 293 learning how to manage data, volumes and mounts inside your containers. 294 295 Go to [Managing Data in Containers](/userguide/dockervolumes). 296