Containers with Docker and Kubernetes · Course book
Chapter 3: A Real Application in Containers
Learning Docker commands is one thing; using Docker every day on a real project is another. This chapter follows a typical web application, a Node.js and Express API with a MongoDB database and a Redis store, through its whole life in containers: a comfortable development setup in which code changes appear instantly, an application made of several cooperating containers, a load balancer in front, deployment to a production server, and finally updates that roll out without downtime. Along the way it explains the small tricks that make the difference between Docker getting in the way and Docker helping.
A development setup that stays out of the way
The first step is a Dockerfile for the application. Following the caching rule from Chapter 1, it copies package.json and runs npm install before copying the rest of the code, so that dependencies are reinstalled only when they actually change. A .dockerignore file excludes the local node_modules folder and other clutter.
Rebuilding the image after every small code edit would make development painfully slow. The solution is a bind mount that maps the project folder on your computer into the container, so the container sees your edits immediately. Combined with a tool such as nodemon, which restarts the Node process whenever a file changes, saving a file updates the running application within a second.
The bind mount creates a problem of its own. It maps the whole project folder, including node_modules, and on your computer that folder may be missing or built for a different operating system, hiding the one installed inside the image. The fix is a small trick: declare an extra anonymous volume for /app/node_modules. Docker gives the more specific path priority, so the container keeps its own installed dependencies while everything else comes from your computer. For extra safety the bind mount can be made read-only, so that nothing running in the container can modify your source files.
Settings such as the port number and database passwords are passed as environment variables. Rather than listing many -e options, they can be kept in a .env file and loaded all at once. That file must never be committed to the code repository, since it holds secrets, so it is listed in .gitignore from the start.
Compose for development and production
Long docker run commands with mounts, ports and variables are hard to remember. A docker-compose.yml file captures them. Since development and production need different settings, a common pattern splits the configuration into a base file and two overrides.
| Setting | Development | Production |
|---|---|---|
| Source code | Bind-mounted from your computer, for instant changes | Copied into the image at build time |
| Dependencies | All, including development tools | Only those needed to run |
| Start command | nodemon, restarting on every change | node, started once |
| Environment | NODE_ENV=development | NODE_ENV=production |
| Secrets | Harmless local values in a .env file | Real values set on the server only |
The base file holds what is shared, and each override adds or changes what differs. Running docker compose with both the base file and the development file merges them. A build argument passed from Compose into the Dockerfile can then decide whether npm install includes development dependencies, so one Dockerfile serves both environments.
One housekeeping detail: volumes outlive the containers that use them. Each time containers are recreated, anonymous volumes can be left behind, slowly filling the disk. Taking an environment down with docker compose down -v removes them, but it must be used carefully, because it also removes named volumes holding real data.
Several containers working together
Adding a database is a matter of adding a service to the Compose file: an official MongoDB image, a named volume so its data survives, and a username and password supplied as environment variables. Compose places all services on a shared network, so the API connects to the database using the service name as the host name, for example mongo on port 27017. No IP addresses are involved, and none would be stable anyway.
Start-up order needs care. depends_on makes Compose start the database before the API, but "started" is not "ready": the database may take a few seconds to accept connections. A robust application therefore retries its database connection a few times before giving up, rather than crashing on the first failure.
With the database in place the application can store data and offer the usual create, read, update and delete operations. User accounts follow: sign-up stores a hash of the password, never the password itself, and log-in compares hashes. To remember who is logged in, the API uses sessions kept in a Redis container. Each logged-in user gets a session identifier in a cookie, and Redis, an in-memory store, maps that identifier to the user's data very quickly. Keeping sessions in Redis instead of in the API's own memory matters for the next step, because it lets several copies of the API share them.
To handle more traffic, the API can run as several identical containers. Nginx, a fast web server, sits in front as a load balancer, passing each incoming request to one of the API containers in turn. With two API containers and 100 requests, each handles about 50, and if one container stops, Nginx can send everything to the other until it returns. Because sessions live in Redis, it does not matter which container receives a logged-in user's next request. When the front end of a website is served from a different address from the API, the API must also allow those cross-origin requests, which in Express is a one-line setting.
Moving to production
For production, a virtual private server running Ubuntu is rented from a cloud provider. Docker and Compose are installed on it, the code is fetched with Git, and the real secrets are set as environment variables on the server itself, never stored in the repository. Running Compose with the production override then starts the whole application.
Updating it reveals a weakness. The simplest workflow is to pull the new code onto the server and rebuild the image there. That works, but building on the production server uses its processor and memory while it is serving users, and the server ends up holding build tools it does not need. A better workflow builds the image on a development machine or in a pipeline, pushes it to Docker Hub, and has the server simply pull the finished image and recreate the container.
Recreating only what changed keeps releases quick. Telling Compose to recreate just the API service, and not its dependencies, avoids restarting the database and Redis every time the application code changes, so users lose their sessions only if Redis itself is restarted.
Even this involves logging in to the server for each release. A tool called Watchtower, itself running as a container, can watch Docker Hub and automatically pull and restart containers when a new image appears. It is convenient for small projects, though larger teams usually prefer deployments triggered deliberately by a pipeline.
Updates without downtime
Recreating a container still means a moment when the old one has stopped and the new one is not yet ready. With Compose on a single server there is no way round that, because Compose was designed for running applications, not for updating them gracefully. This is where an orchestrator is needed.
Docker Swarm is built into Docker and is the gentlest one to start with. Running docker swarm init turns the server into a single-node swarm, and the existing Compose file, with a few extra deploy settings, can be deployed as a stack. In those settings you state how many replicas of the API to run, say 8, and how to update them: for example, 2 at a time with a 15-second pause between batches. When a new image is released, Swarm replaces the replicas batch by batch, 4 batches in all, while the remaining 6 keep serving users, and it restarts any replica that fails along the way.
Check your understanding
- Why does the Dockerfile copy package.json and install dependencies before copying the rest of the code?
- What problem does the anonymous volume for node_modules solve?
- Give two settings that typically differ between development and production.
- Why should the API retry its database connection at start-up?
- Why must sessions be kept in Redis once there is more than one API container?
- Why is building images on the production server a poor workflow?
- A service has 12 replicas updated 3 at a time. How many batches does a rolling update take, and how many replicas keep serving during each? (Answer: 4 batches; 9 replicas.)
This course book is available to read online only at tech-academy.chrysolites.org.