beginner35 minby DevFox

Your First Containerised App

The capstone: take a small application from bare source to a built, configured, published image running behind Compose with persistent data — every step from the earlier lessons in one pass.

Docker

Twelve lessons of pieces. This one puts them together, in the order you would actually do it, on an application that needs all of them: a small web service with a database and a cache, configured from the environment, built as a small non-root image, running behind Compose with data that survives, and published so someone else can run it.

Follow it end to end on your own machine. By the finish you will have a project you could hand to a colleague with a single instruction — docker compose up — and a checklist you can apply to anything you containerise afterwards.

Write the .dockerignore first
Before the Dockerfile, so no secret and no cache is ever in a build context — not even once.
Write the Dockerfile
Multi-stage, non-root, health-checked. The destination from the earlier lessons, not a first draft.
Describe the whole system in compose.yaml
Database, cache, volumes, health conditions, configuration from .env.
Run it, then destroy it and run it again
The step people skip. It is the only proof your data lives outside the container.
Add a development override
Bind mount and a reloading server, kept out of the base file so the base stays deployable.
Check the image, then publish it
Two ten-second checks for secrets, then tag with a real version and push.

The order matters: each step is cheaper to get right before the next one exists

The application

A note-taking API: it stores notes in Postgres, counts views in Redis, and reports its own health. Small enough to read in one sitting and real enough to exercise everything.

Make a directory and create app.py:

And requirements.txt:

Two things to notice, both deliberate. The two URLs are read with bracket access, so the process refuses to start without them rather than failing on its first request. And there is a /health endpoint that actually touches both dependencies — a health check that only proves the web framework is awake is worth very little.

Step 1: keep the context clean

Before writing the Dockerfile, write the .dockerignore. Doing it first means no secret and no cache is ever in a build context, not even once:

Step 2: a Dockerfile worth shipping

This is the multi-stage, non-root, health-checked version — the destination from the earlier lessons rather than a first draft:

Every line is one of the earlier lessons. Dependencies are copied and installed before the source, so the cache survives a code change. The virtual environment is built in a stage that is thrown away. PYTHONUNBUFFERED=1 keeps docker logs honest. The process runs as appuser. The bind address is 0.0.0.0, not 127.0.0.1. And the command is gunicorn in the bracket form, so it is process 1 and hears docker stop.

Build it and check what you got:

Step 3: describe the whole system

compose.yaml, with the database and cache alongside:

And the two files that go with it — one committed, one not:

The :?set it suffix means Compose refuses to start with a clear message rather than silently building a database URL with an empty password. Neither database nor cache publishes a port: the API reaches them at db:5432 and cache:6379 over the project network, and nothing outside needs to.

Step 4: run it and prove it works

Every service should read healthy. Then exercise it:

Now the test that matters, and the one people skip:

If the note survived, your storage is genuinely outside the container. If it did not, the volume is misconfigured — and finding that out now is the entire reason to try it.

Step 5: a development mode

For working on the code you want edits to take effect immediately. Compose reads compose.override.yaml automatically, so development differences live there and the base file stays deployable:

Edit app.py, save, and hit the endpoint again — no rebuild.

docker compose up

Base plus override — how you work.

Your source is bind-mounted, the development server reloads on save, and debug output is on.

Compose picks up compose.override.yaml without being asked.

docker compose -f compose.yaml up -d

Base only — what actually deploys.

Naming the file explicitly stops the override being applied.

This is the configuration a server runs, so it is worth running yourself before you claim it works.

Two commands, one project. The override file is the only difference between them.

Step 6: publish it

Check the image before it becomes public, then tag and push:

Then prove the push, from an empty local cache:

If your target servers are amd64 and you built on Apple silicon, build for both:

The checklist

Apply this to anything you containerise from here on. Each line is one lesson from this course.

Cheat sheet

Where to go next

You can now containerise an application properly: build it small, run it unprivileged, configure it from outside, keep its data, wire its services together, diagnose it when it fails, and publish it for someone else to run. That is the whole of Docker that most work needs.

The natural next step is what happens when one machine is not enough. Compose starts your services on the host you are sitting at; it cannot move a container when a machine dies, spread copies across several hosts, or roll out a new version without dropping requests. Kubernetes is the answer to those questions, and everything you have learned here is its input — a container is still a container, and the image you just published is exactly what a cluster runs.

Before that, do the most useful exercise available: containerise something of your own, working down the checklist above. The first time you do it without this lesson open, it will have become a skill.