Writing a Dockerfile

Both problems come from how a Dockerfile works: every line builds a layer, and layers are both reused and kept. This lesson is about writing each line on purpose.

A Dockerfile is a text file of instructions for building an image. Docker runs them from top to bottom. Most lines change the files in the image, and each of those saves its result as a layer: a snapshot of what that one line changed.

Every instruction, in one table

CMD or ENTRYPOINT

Both say what runs when a container starts. The difference shows when you add words after the image name on docker run:

Use CMD for an app like QuickCart’s. It’s easy to swap for something else when you’re debugging. ENTRYPOINT suits images that are really one tool, like a command-line program, where every run calls the same thing.

Brackets or no brackets

CMD and ENTRYPOINT can be written two ways:

When Docker stops a container, it sends the main process a polite “please stop” signal, called SIGTERM, and waits 10 seconds. Then it forces it. With the shell form, the signal goes to the shell, and many shells never pass it on. Gunicorn doesn’t hear it, so it’s killed in the middle of answering people. Always use the bracket form. Releases without downtime shows what this costs during a deploy.

The cache, and why the order matters

On a rebuild, Docker looks at each line in turn. If the line hasn’t changed, and the files it reads haven’t changed, and nothing above it rebuilt, Docker reuses the saved layer. The build output says CACHED.

The moment one line has to run again, every line below it runs again too, because each layer is built on top of the one before.

So the rule is: put what changes rarely at the top, and what changes often at the bottom. QuickCart’s libraries change once a month. The code changes many times a day. So the Dockerfile copies requirements.txt and installs the libraries first, and copies the code last.

What goes into the build

docker build . sends the whole folder, called the build context, to the builder. A COPY . . line then copies all of it into the image, including .git, local virtual environments and any .env file.

A file called .dockerignore, next to the Dockerfile, lists what to leave out. It works like .gitignore. It keeps builds fast and secrets out.

Don’t run as root

Inside a container, the app runs as root unless you say otherwise. If someone finds a hole in the app, they get root’s power inside the container, and containers share the host’s kernel, so a root break-in is much more dangerous. Two lines fix it: create a normal user, then switch to it.

USER is given the number, not the name. The name only exists inside the image’s own user list. Tools outside the image, like Kubernetes checking that a container isn’t root, can only trust a number. The Dockerfile linter hadolint warns about a name for exactly that reason.

This is also why the app listens on port 8080 rather than 80. On Linux, ports below 1024 have traditionally needed root, and not every platform relaxes that rule. A high port always works for a normal user, and the load balancer in front doesn’t mind which port it forwards to.

Pin the base image

FROM decides most of what’s in your image. How precisely you name it decides whether next month’s build gets the same thing:

slim means a small Debian with only what Python needs. The full python:3.12 image is several times larger, because it also carries compilers and build tools. Images and containers explains tags and digests.

Multi-stage builds

Some apps need big tools to build and none of them to run. A multi-stage build has more than one FROM. The early stages build things; only the last stage becomes the image, and it copies in just the finished result.

FROM python:3.12 AS build
WORKDIR /build
COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

FROM python:3.12-slim
WORKDIR /app
RUN useradd --create-home --uid 1001 appuser
COPY --from=build /install /usr/local
COPY app.py .
USER 1001
EXPOSE 8080
CMD ["gunicorn", "--bind", "0.0.0.0:8080", "app:app"]

For QuickCart’s two small Python libraries this saves little, because nothing needs compiling. It matters a lot for Go, Java or a front-end build, where the build tools are hundreds of megabytes and the finished program is small.

Below is QuickCart’s Dockerfile, already built once. Pick what you edit and choose Rebuild. Then switch to the Dockerfile that copies everything first and do the same edit again.

What to notice: both Dockerfiles install exactly the same libraries. The only difference is the order of two lines, and it turns a one-second rebuild into a forty-second one, on every single code change.

Free — everything runs on your own computer.

You’ll write QuickCart’s order service and its Dockerfile, build it, run it, and watch the cache work and fail. About 30 minutes.

You need Docker Desktop installed and running. Set up your computer covers it. Check with:

docker version

1. Write the app

   Make a folder called order-service and open it in your editor. Create these two files in it.

   app.pyCopy

   import os
   import socket
   
   from flask import Flask, jsonify
   
   app = Flask(__name__)
   VERSION = os.environ.get("APP_VERSION", "v1")
   
   ORDERS = [
       {"id": 1, "item": "margherita pizza", "qty": 2},
       {"id": 2, "item": "pad thai", "qty": 1},
       {"id": 3, "item": "falafel wrap", "qty": 3},
   ]
   
   
   @app.get("/health")
   def health():
       return jsonify(status="ok", version=VERSION)
   
   
   @app.get("/")
   def home():
       return jsonify(service="order-service", version=VERSION, served_by=socket.gethostname())
   
   
   @app.get("/orders")
   def orders():
       return jsonify(version=VERSION, count=len(ORDERS), orders=ORDERS)

   Page	What it returns
   /health	ok and the version. Health checks call this to ask “are you working?”
   /	The version, and served_by: the name of the machine, or container, that answered
   /orders	Three sample orders

   requirements.txtCopy

   flask==3.0.3
   gunicorn==23.0.0

   Line	What it means
   flask==3.0.3	Flask, the web framework the app is written in, exactly version 3.0.3
   gunicorn==23.0.0	Gunicorn, the server that runs a Flask app properly, with several workers

   Exact versions (==) mean every build installs the same libraries: no surprise upgrades.

2. Write the Dockerfile and .dockerignore

   In the same folder, create Dockerfile, with no extension:

   DockerfileCopy

   FROM python:3.12-slim
   WORKDIR /app
   RUN useradd --create-home --uid 1001 appuser
   COPY requirements.txt .
   RUN pip install --no-cache-dir -r requirements.txt
   COPY app.py .
   USER 1001
   ARG APP_VERSION=v1
   ENV APP_VERSION=$APP_VERSION
   EXPOSE 8080
   HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
     CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8080/health', timeout=2)"]
   CMD ["gunicorn", "--bind", "0.0.0.0:8080", "--workers", "2", "--graceful-timeout", "20", "app:app"]

   Line	What it does	Why it’s here
   FROM python:3.12-slim	Start from a small Debian with Python 3.12	Pinned to 3.12, so it can’t jump versions
   WORKDIR /app	Work in /app from now on	Keeps the app’s files together
   RUN useradd …	Create appuser, number 1001	Never changes, so it sits near the top and stays cached
   COPY requirements.txt .	Copy only the library list	So the next line depends on this file alone
   RUN pip install --no-cache-dir -r requirements.txt	Install the libraries. --no-cache-dir stops pip keeping its download cache, which would only make the image bigger	The slow step. Reused until requirements.txt changes
   COPY app.py .	Copy the code	Last, because it changes most
   USER 1001	Run the app as appuser	Not root
   ARG APP_VERSION=v1	A build-time value, v1 unless you pass --build-arg APP_VERSION=v2	Lets later lessons build a v2 from the same code
   ENV APP_VERSION=$APP_VERSION	Copy that value into a setting the running app reads	ARG disappears after the build; ENV stays
   EXPOSE 8080	Note the port	Documentation for people and tools
   HEALTHCHECK …	Every 30 seconds, fetch /health with Python. Wait up to 3 seconds; after 3 failures in a row, mark the container unhealthy. Failures in the first 10 seconds don’t count	The slim image has no curl, so the check uses Python, which is already there
   CMD [ … ]	Start gunicorn on port 8080 with 2 workers. On a stop signal, give requests in progress up to 20 seconds to finish	Bracket form, so gunicorn hears the stop signal

   Now create .dockerignore, to keep anything else in the folder out of the build:

   .dockerignoreCopy

   .git
   .venv
   __pycache__
   *.pyc
   .env
   *.pem
   Dockerfile*
   .dockerignore

   Line	Leaves out
   .git	Your git history, which can be large and may hold old secrets
   .venv, __pycache__, *.pyc	Python’s local files, which belong to your computer, not the image
   .env, *.pem	Settings files and keys: secrets
   Dockerfile*, .dockerignore	The build files themselves. Docker still reads them; they just aren’t copied into the image

   This Dockerfile copies files by name, so .dockerignore is a second line of defence. It matters most the day someone writes COPY . ..

3. Build the image

   In the terminal, go into the folder:

   TerminalCopy

   cd order-service

   Part	What it means
   cd order-service	move into the folder, so the next commands use its files

   TerminalCopy

   docker build -t order-service:v1 .

   Part	What it means
   docker build	build an image from a Dockerfile
   -t order-service:v1	name it order-service, with the tag v1
   .	the build context: send this folder to the builder. Docker looks for Dockerfile in it

   The lines that matter look like this

    => [1/6] FROM docker.io/library/python:3.12-slim
    => [2/6] WORKDIR /app
    => [3/6] RUN useradd --create-home --uid 1001 appuser
    => [4/6] COPY requirements.txt .
    => [5/6] RUN pip install --no-cache-dir -r requirements.txt
    => [6/6] COPY app.py .
    => exporting to image
    => => naming to docker.io/library/order-service:v1

   There are more lines than this, and each has a time on the right. The first build downloads the base image, so it takes longest. Only six lines are numbered: USER, ARG, ENV, EXPOSE, HEALTHCHECK and CMD are settings, not layers.

4. Run it and check it

   TerminalCopy

   docker run -d -p 8080:8080 --name orders order-service:v1

   Part	What it means
   docker run	start a container from an image
   -d	detached: run in the background and give you the terminal back
   -p 8080:8080	connect port 8080 on your computer to port 8080 in the container
   --name orders	call the container orders, so later commands can use that name
   order-service:v1	the image to start

   You should see

   A long line of letters and numbers: the new container’s ID. It started.

   TerminalCopy

   curl localhost:8080/health

   Part	What it means
   curl	fetch a web address and print the answer
   localhost:8080	your own computer, port 8080, which -p connects to the container
   /health	the page to fetch

   You should see

   {"status":"ok","version":"v1"}

   TerminalCopy

   curl localhost:8080/

   Part	What it means
   /	the home page, which says who answered

   You should see

   {"served_by":"4d29ffd981e4","service":"order-service","version":"v1"}

   served_by is the container’s own name for itself: the first 12 characters of its ID. Yours will be different.

   TerminalCopy

   docker ps

   Part	What it means
   docker ps	list running containers

   You should see

   One row, named orders. Its STATUS says Up with (health: starting), and about 30 seconds later, once the first check has passed, (healthy). That’s the HEALTHCHECK line at work.

   TerminalCopy

   docker exec orders whoami

   Part	What it means
   docker exec	run a command inside a running container
   orders	which container
   whoami	the command: print the current user

   You should see

   appuser

   Not root. User 1001 is appuser, because that’s the name the useradd line gave it.

5. Change the code and watch the cache

   Open app.py and add one line at the very end, a comment:

   app.pyCopy

   import os
   import socket
   
   from flask import Flask, jsonify
   
   app = Flask(__name__)
   VERSION = os.environ.get("APP_VERSION", "v1")
   
   ORDERS = [
       {"id": 1, "item": "margherita pizza", "qty": 2},
       {"id": 2, "item": "pad thai", "qty": 1},
       {"id": 3, "item": "falafel wrap", "qty": 3},
   ]
   
   
   @app.get("/health")
   def health():
       return jsonify(status="ok", version=VERSION)
   
   
   @app.get("/")
   def home():
       return jsonify(service="order-service", version=VERSION, served_by=socket.gethostname())
   
   
   @app.get("/orders")
   def orders():
       return jsonify(version=VERSION, count=len(ORDERS), orders=ORDERS)
   
   # a small change, to test the cache

   Save it and build again, as a new tag:

   TerminalCopy

   docker build -t order-service:v2 .

   Part	What it means
   -t order-service:v2	the same name, a new tag, so you keep v1 as it was

   Look for CACHED

    => CACHED [2/6] WORKDIR /app
    => CACHED [3/6] RUN useradd --create-home --uid 1001 appuser
    => CACHED [4/6] COPY requirements.txt .
    => CACHED [5/6] RUN pip install --no-cache-dir -r requirements.txt
    => [6/6] COPY app.py .

   Only the step that reads app.py ran. The whole build takes a second or two.

6. Build it in the wrong order

   Create a second Dockerfile called Dockerfile.bad. It copies the whole folder before installing:

   Dockerfile.badCopy

   FROM python:3.12-slim
   WORKDIR /app
   RUN useradd --create-home --uid 1001 appuser
   COPY . .
   RUN pip install --no-cache-dir -r requirements.txt
   USER 1001
   EXPOSE 8080
   CMD ["gunicorn", "--bind", "0.0.0.0:8080", "app:app"]

   Build it once, so there’s a cache to reuse:

   TerminalCopy

   docker build -f Dockerfile.bad -t order-service:bad .

   Part	What it means
   -f Dockerfile.bad	use this file instead of the one called Dockerfile
   -t order-service:bad	tag the result bad
   .	the same folder as before

   Now change the comment at the end of app.py, so it reads # a second small change, save, and run the same build command again.

   This time

    => CACHED [2/5] WORKDIR /app
    => CACHED [3/5] RUN useradd --create-home --uid 1001 appuser
    => [4/5] COPY . .
    => [5/5] RUN pip install --no-cache-dir -r requirements.txt

   pip install ran again, for a comment. COPY . . reads app.py, so its input changed, and every step below it had to rebuild. With two small libraries it’s a few seconds; with a real app’s libraries it’s minutes, on every change.

7. See CMD and ENTRYPOINT side by side

   Create two tiny Dockerfiles. First, Dockerfile.cmd:

   Dockerfile.cmdCopy

   FROM python:3.12-slim
   CMD ["echo", "this is the default"]

   Then Dockerfile.ep:

   Dockerfile.epCopy

   FROM python:3.12-slim
   ENTRYPOINT ["echo", "always starts with this:"]

   Build both:

   TerminalCopy

   docker build -f Dockerfile.cmd -t cmd-demo .

   Part	What it means
   -f Dockerfile.cmd	build from the CMD example
   -t cmd-demo	name it cmd-demo. With no tag, Docker adds latest

   TerminalCopy

   docker build -f Dockerfile.ep -t ep-demo .

   Part	What it means
   -f Dockerfile.ep -t ep-demo	the same, for the ENTRYPOINT example

   Run the CMD one twice, once with extra words:

   TerminalCopy

   docker run --rm cmd-demo

   Part	What it means
   --rm	delete the container as soon as it finishes
   cmd-demo	the image; nothing after it, so CMD runs

   You should see

   this is the default

   TerminalCopy

   docker run --rm cmd-demo echo "I replaced it"

   Part	What it means
   echo "I replaced it"	words after the image name. They replace CMD

   You should see

   I replaced it

   Now the ENTRYPOINT one:

   TerminalCopy

   docker run --rm ep-demo and this was added

   Part	What it means
   ep-demo	the image with the ENTRYPOINT
   and this was added	words after the image name. They’re added to the ENTRYPOINT

   You should see

   always starts with this: and this was added

8. Stop it cleanly

   TerminalCopy

   docker stop orders

   Part	What it means
   docker stop	send the container’s main process SIGTERM, wait up to 10 seconds, then force it
   orders	which container

   You should see

   orders

   It returns in about a second, not ten. Look at what gunicorn did:

   TerminalCopy

   docker logs orders

   Part	What it means
   docker logs	print everything the container wrote to its output, even after it stopped

   The last lines

   [INFO] Handling signal: term
   [INFO] Worker exiting (pid: 7)
   [INFO] Worker exiting (pid: 8)
   [INFO] Shutting down: Master

   Each line also starts with a date and a number; yours will differ. Gunicorn heard the signal, let its workers finish, and exited. That’s the bracket form of CMD doing its job.

9. Clean-up step: Clean up

   Remove the container:

   TerminalCopy

   docker rm orders

   Part	What it means
   docker rm	delete a stopped container

   You should see

   orders

   Then remove the images you built:

   TerminalCopy

   docker image rm order-service:v1 order-service:v2 order-service:bad cmd-demo ep-demo

   Part	What it means
   docker image rm	delete images from your computer
   order-service:v1 and the rest	every image this lab built, by name and tag

   You should see

   An Untagged: line for each name, and some Deleted: lines. Nothing from this lab is left except the files in your folder.

   Keep the order-service folder. Data and networking and Storing images: ECR build from it again.