Write a Dockerfile That Builds on the First Try

A Dockerfile is a text file of build steps. Most failed first builds come from the same four mistakes: the wrong file name, the wrong folder, a file that is not in the build context, and a command that is never found. This page writes a small Dockerfile that avoids all four, then breaks it on purpose so you can read the error.

The app

Make an empty folder and put two files in it. The first is a tiny Python program.

print("built and running")

The Dockerfile

The second file is named Dockerfile, with a capital D and no extension. Windows Notepad likes to add .txt to the end, so check the file name in File Explorer with "File name extensions" switched on.

FROM python:3.14-alpine
WORKDIR /app
COPY app.py .
CMD ["python3", "app.py"]

Line by line:

1. FROM picks the starting image. A pinned tag such as 3.14-alpine builds the same way next month. latest does not.
2. WORKDIR sets the folder inside the image for the steps after it. It creates the folder if needed.
3. COPY app.py . copies the file from your folder into the image's working folder. The dot is the destination, /app.
4. CMD is the command a container runs when you start it. Write it as a JSON list, with double quotes, as shown.

Build and run

The dot at the end of docker build is the build context: the folder Docker may copy from. The tag after -t is the name you give the image. -q keeps the output down to the image ID.

docker build -q -t tryfirst:1 .

sha256:5e5c23209dc4afb3f251c029d4c0017de712a1c444fa35e904229fac67d0d7a3

docker run --rm tryfirst:1

built and running

That is the whole loop: write, build, run. Without -q Docker prints each step as it goes, and you can see which step failed.

Error: a file that is not in the build context

COPY can only see files inside the context folder. Here is the same Dockerfile, pointed at a file that does not exist.

FROM python:3.14-alpine
WORKDIR /app
COPY missing.py .
CMD ["python3", "missing.py"]

docker build -q -f Dockerfile.bad -t tryfirst:bad .

>>> COPY missing.py .
ERROR: failed to build: failed to solve: failed to compute cache key

Docker prints the failing line of the Dockerfile with >>> in front of it. The last words of the long error line are "/missing.py": not found, so the message names the file and says "not found". Check three things: the spelling, that the file really sits in the context folder, and that .dockerignore does not list it. -f told Docker which Dockerfile to use, which is the way to build from a file with another name.

Error: no Dockerfile

Run the build from a folder that has none, and Docker says so.

New-Item -ItemType Directory -Force -Name emptydir | Out-Null
docker build -q -t tryfirst:none .\emptydir

failed to read dockerfile

If you see this, you are in the wrong folder, or the file has the wrong name. A name such as Dockerfile.txt does not count.

A habit that saves rebuild time

Docker reuses a step when nothing before it changed. Put the steps that rarely change at the top, and the ones that change often, such as copying your code, at the bottom. A change to app.py then rebuilds only the last steps.

Related course: Docker for Beginners.