This challenge was prepared for you by the iximiuz Labs team.

Challenge

Learner activity No attempts yet

Launch a Multi-Container Web Application, Then Upgrade Its Backend

Compare different ways to connect Docker containers and their trade-offs using a simple two-container web application.

In this challenge, you'll launch a small web application consisting of two containers: a UI frontend and an API backend.

Both components are already packaged as Docker images. You'll run them on an existing Docker host, server-01, using plain Docker commands. For educational purposes, Docker Compose and container orchestrators aren't available in this environment.

To make things a little bit more realistic, the server also runs containers unrelated to the application, including a log shipper, a metrics collector, and a background worker. You'll be sharing the Docker host with these workloads, so leave them running and avoid changing their configuration.

The following images are available:

frontend - The web UI. It listens on port 8080 and fetches products from the URL specified by the BACKEND_URL environment variable (http://ADDR:PORT).
backend - The API backend. It listens on port 3000 and requires no extra configuration.

The frontend and the backend containers on server-01.

1. Deploy the application

Start the frontend:v1 and backend:v1 containers and make the frontend available on port 80 of server-01. The Application page should display the products served by backend v1.

You can choose how the frontend connects to the backend. The only requirement is that the web UI is accessible from outside the Docker host - the backend doesn't need to be exposed.

Hint 1

Every Docker container has its own network stack, including its own IP addresses and ports. By default, Docker attaches new containers to a network called bridge. Containers on this network can communicate directly using their IP addresses - no port publishing or extra network configuration is required.

See Docker 101: List Docker Networks and Inspect the Default Bridge for more.

Hint 2

One way to connect the frontend to the backend is to start the backend first, find its container IP address, and pass that address to the frontend through BACKEND_URL.

The docker inspect command shows a container's network settings, including its IP address. If the backend container is named api, run:

docker inspect api

For example, if the backend has the address 172.17.0.9, you can configure the frontend with:

BACKEND_URL=http://172.17.0.9:3000

See Docker 101: Reach a Container Without Publishing a Port for more on direct container IP connectivity.

Hint 3

Containers on a bridge network can reach each other by IP, but machines outside the Docker host normally cannot reach these addresses directly. To make the frontend accessible through port 80 of server-01, you need to publish its listening port.

The -p flag of docker run maps a port on the host to a port inside the container:

-p HOST_PORT:CONTAINER_PORT

The frontend listens on port 8080, so publish that port on port 80 of the host.

See Docker 101: Publish a Container Port to Access the App from the Host.

2. Remove the old backend

Now that the application is working, it's time to upgrade its backend. The upgrade starts with retiring the old version.

Stop and remove the backend:v1 container. To keep the Docker host tidy, don't leave the stopped container behind.

Hint 4

A docker restart doesn't upgrade a container. Each container is created from a particular image, and restarting it doesn't change that image.

To upgrade the backend, stop and remove the old container using docker stop and docker rm. You'll then be able to create a new container using backend:v2.

If you gave the old container a name such as api, removing it also frees that name for the replacement.

3. Start the new backend

Start the backend:v2 container. The application should work again and display the products served by backend v2.

You may need to adjust how the containers connect to each other, depending on the approach you chose in the first step.

Hint 5

When a container is removed, Docker releases its IP address back to the network's address pool. That address can then be assigned to another container.

Since server-01 also runs unrelated workloads, don't assume that the new backend will get the same address as the old one.

If the frontend was configured to connect directly to the backend's IP address, check whether that address has changed. You can inspect the new backend container to find its current address:

docker inspect api

Then compare it with the value of BACKEND_URL in the frontend container:

docker inspect web

A container's environment variables are fixed when it is created. If BACKEND_URL still points to the old backend IP, you'll need to recreate the frontend with the new address.

Hint 6

Direct container IP addresses aren't the only option to connect containers. You can also publish the backend's port on the Docker host and configure the frontend to connect through that published port. For example, publishing the backend with -p 3000:3000 makes its port 3000 available through the host's addresses.

Containers on the bridge network can access a gateway address that belongs to the Docker host (often 172.17.0.1), and Docker also provides a special host-gateway value for the --add-host option to avoid hardcoding such an address:

--add-host=host.docker.internal:host-gateway

With this option, the frontend can use:

BACKEND_URL=http://host.docker.internal:3000

This is a valid way to connect the containers, and it spares you the need to reconfigure the frontend if the backend's IP changes. But it has significant drawbacks:

Publishing the backend port on all host interfaces may also expose it to other undesired clients.
Manual port management can lead to port conflicts, especially when the number of services on the Docker host grows.
Traffic through published ports undergoes NAT, so some performance overhead is expected.

For a closer look at host-gateway, see Connect a Container to a Service Running on the Docker Host.

Hint 7

Docker also supports user-defined bridge networks, which is probably the best way forward for this task. Unlike the default bridge network, they provide automatic name resolution between containers.

You can create a new network with:

docker network create app-net

Then attach containers to it when starting them:

docker run --network app-net --name api ...

Docker's embedded DNS server lets other containers on app-net reach this container by the name api, without looking up its IP address.

If you start both the frontend and backend on app-net, the frontend can use:

BACKEND_URL=http://api:3000

The default bridge network doesn't support this kind of automatic name resolution, even though containers on it can communicate by IP addresses.

Hint 8

Before user-defined networks and automatic DNS were introduced, Docker provided the --link option to help containers on the default bridge network find each other by name. For example:

docker run --link api:api frontend:v1

Docker would add the backend's address to the frontend container's /etc/hosts file and update it when the linked container restarted. However, legacy links don't handle container replacement well, and Docker has deprecated them on the default bridge network.

You may still encounter --link in old tutorials or deployment scripts, but for new applications, prefer user-defined bridge networks and their built-in DNS.

By default, every container gets its own IP address, and containers on the same bridge network (e.g., the default) can reach each other using these addresses.

The simplest way to connect the frontend to the backend is to put the backend's IP address into BACKEND_URL. This approach works for the initial deployment, but the address belongs to a particular container. The upgraded backend may get a different address, so you'll need to recreate the frontend to make the application work again.

Connecting the containers by IP address.

1. Deploy the application

Start the backend first, because the frontend needs to know its address:

docker run -d --name api backend:v1

Look up the IP address of the new container:

docker inspect -f '{{.NetworkSettings.Networks.bridge.IPAddress}}' api

172.17.0.5

Now, start the frontend pointing it to the backend's address (and publishing its port 8080 on port 80 of server-01 to access its web UI):

docker run -d --name web \
    -p 80:8080 \
    -e BACKEND_URL=http://172.17.0.5:3000 \
    frontend:v1

The Application page should now display the products and Backend version: v1 at the bottom.

2. Remove the old backend

An existing container cannot switch to another image, so the upgrade starts with stopping and removing the old api container:

docker stop api
docker rm api

3. Start the new backend

Start a new api container from the backend:v2 image:

docker run -d --name api backend:v2

Reload the Application page. You may see an error instead of the products:

Cannot load products from the backend at http://172.17.0.5:3000: Connection refused

The frontend still sends its requests to 172.17.0.5, but this address can now be used by some other container on the host. Check which containers have which addresses now:

docker inspect \
    -f '{{.Name}} {{.NetworkSettings.Networks.bridge.IPAddress}}' \
    $(docker ps -q)

/api 172.17.0.2
/background-worker-2 172.17.0.5
/web 172.17.0.6
/log-shipper 172.17.0.4
/metrics-exporter 172.17.0.3

Important

Container names and addresses may differ across challenge runs.

The new backend container got a different address. The old one went to the background-worker-2 container, which started while you were performing the backend upgrade.

Docker gives a container an address that is free at the moment the container starts, and it doesn't remember which container had which address before. In this challenge, you're sharing the Docker host with other workloads, so a released address can go to any of them.

Note

This time, the failure is easy to notice. The worker doesn't listen on port 3000, so the frontend's requests fail right away. If the new owner of the address listened on the same port, the frontend would silently send its requests to the wrong service.

4. Reconnect the frontend

The environment variables of a container cannot be changed after it's created, so you'll need to recreate the frontend to point it to the new address:

docker stop web
docker rm web

docker run -d --name web \
    -p 80:8080 \
    -e BACKEND_URL=http://172.17.0.2:3000 \
    frontend:v1

The Application page should now display Backend version: v2.

The application is working again, but you'd have to redeploy the frontend after every backend upgrade. In a bigger application, every container that talks to the backend would need the same treatment. Solution 2 shows how to avoid hardcoding container addresses.

Important

Docker also has a legacy --link flag that adds the address of another container to the container's /etc/hosts file:

docker run -d --name web --link api ...

Links are a remnant of the times before user-defined networks. They don't survive the replacement of the linked container either.

Docker 29+ warns that links on the default bridge network are deprecated and will be removed in a future release.

By default, Docker attaches new containers to a network called bridge. Docker also lets you create bridge networks of your own and choose which containers to attach to them. Containers on such a user-defined network can reach each other by name (think DNS), so the frontend can keep using the same backend URL after the upgrade.

Connecting the containers through a user-defined network.

A user-defined bridge network works the same way as the default one. Every container on it has its own IP address, the containers can talk to each other directly using these addresses, and you can publish their ports on the host with the -p flag. Additionally, Docker runs an embedded DNS server for every user-defined network, so its containers can reach each other by container name.

With the frontend and the backend on the same user-defined network, the frontend can use http://api:3000 as the backend URL, where api is the name of the backend container. Docker resolves the api name to the address of the container that has this name at the moment. When the backend:v2 container takes over the name, the frontend starts talking to it without any changes.

1. Deploy the application

Create a bridge network for the application:

docker network create app

Start both containers on this network, and use the backend's container name in the frontend's BACKEND_URL variable:

docker run -d --name api \
    --network app \
    backend:v1

docker run -d --name web \
    --network app \
    -p 80:8080 \
    -e BACKEND_URL=http://api:3000 \
    frontend:v1

The Application page should now display the products and Backend version: v1 at the bottom.

Note

Containers on user-defined networks send their DNS queries to Docker's embedded DNS server at 127.0.0.11:

docker exec web cat /etc/resolv.conf

nameserver 127.0.0.11
options ndots:0

The server knows the names (and network aliases) of all containers on the network and resolves them to the current addresses of these containers:

docker exec web getent hosts api

172.18.0.2        api  api

2. Remove the old backend

Stop and remove the old api container:

docker stop api
docker rm api

3. Start the new backend

Start a new container from the backend:v2 image under the same name and on the same network:

docker run -d --name api --network app backend:v2

The frontend doesn't need any changes, and the Application page should now display Backend version: v2. Whatever address the new container gets, the api name now resolves to it.

Note

Note that the name-based connection only helps when the client resolves the name again. The frontend in this challenge opens a new connection for every request, so it starts using the new backend right away.

Applications that keep long-lived connections or cache DNS responses need to reconnect (and resolve the name again) after the old backend goes away. Docker doesn't move existing connections to the new container.

The first two solutions connect the frontend directly to the backend container, either by the container's IP address or by its name. The alternative is to make the backend port available on the host and connect the frontend to the Docker host. For instance, you can publish the backend's port on the host and point the frontend to the host with the --add-host <name>:host-gateway flag.

This approach has a few advantages over the other two solutions:

The frontend depends only on the address of the host, so it doesn't need to be recreated after the upgrade (unlike in Solution 1).
It works on the default bridge network, so there is no extra network to create (unlike in Solution 2).
The two containers don't need to share a network at all. The backend can sit on another network or even run directly on the host, and the frontend's configuration stays the same.

But it also has a few rather significant downsides (see below).

Connecting the containers through a published port.

1. Deploy the application

Start the backend and publish its port 3000 on server-01:

docker run -d --name api \
    -p 3000:3000 \
    backend:v1

Start the frontend with an /etc/hosts entry pointing to the Docker host, and use this entry in the BACKEND_URL variable:

docker run -d --name web \
    -p 80:8080 \
    --add-host host.docker.internal:host-gateway \
    -e BACKEND_URL=http://host.docker.internal:3000 \
    frontend:v1

Inside the frontend container, host.docker.internal resolves to the address of the default bridge on the host:

docker exec web grep host.docker.internal /etc/hosts

172.17.0.1  host.docker.internal

The Application page should now display the products and Backend version: v1 at the bottom.

2. Remove the old backend

Stop and remove the old api container:

docker stop api
docker rm api

Port 3000 of the server is free again.

3. Start the new backend

Start a new api container from the backend:v2 image, and publish the same port:

docker run -d --name api -p 3000:3000 backend:v2

The frontend doesn't need any changes, and the Application page should now display Backend version: v2. The address of the new container doesn't matter, because the frontend never uses it.

Important

Downsides of the port publishing approach

The backend is exposed, although only the web UI had to be accessible from outside the Docker host. The -p 3000:3000 flag publishes the port on all addresses of server-01. You can publish the port on the bridge address of the host instead (-p 172.17.0.1:3000:3000), but such a port may still be reachable from other machines.
Publishing the port on localhost is not an option. The frontend connects to the bridge address of the host, and a container cannot reach a port bound to the host's localhost.
The host port is a shared resource. Only one container on server-01 can publish port 3000, so the port can conflict with other workloads, and the old backend has to release it before the new one starts.
The traffic takes a detour through the host. The backend sees the bridge address of the host as the source of every request, so it cannot tell which container sent it.

Challenge progress

Tasks

Launch a Multi-Container Web Application, Then Upgrade Its Backend

1. Deploy the application

2. Remove the old backend

3. Start the new backend

1. Deploy the application

2. Remove the old backend

3. Start the new backend

4. Reconnect the frontend

1. Deploy the application

2. Remove the old backend

3. Start the new backend

1. Deploy the application

2. Remove the old backend

3. Start the new backend