Platform Engineering · Lesson 156

Docker Lab: Build Your First Image and Run It

Lesson 140 taught you to build and run an image. This lab is where you do it on your own machine. You write a five-line Dockerfile, you build the image, you run it, you curl it and watch it answer, and you push it to a registry and pull it back. By the end you have an image that answers hello, and you know the difference between an image and a container, because you built one and ran the other.

Difficulty: Beginner · Know this first: Lesson 140 — Docker from Scratch; Docker Desktop installed and running

Run it as:

When it breaks, I check

One thing to remember

Where the time goes

Every hop charges rent in milliseconds. The bar below is a worked example for this lesson's scenario — not a measurement from a live system — but the shape is honest: on a cache hit the trip is almost free, on a miss the kitchen eats the budget. Step through the lesson or switch the scenario and watch the bar change.

Extra diagram · from scratch to master

The first image, mapped: app, build, run, push, pull

Start with three lines of app. Add one box at a time until the pulled image answers hello.

7 boxes on the trip1 image1 expired login
Docker
0 min
App
1 min
Dockerfile
1 min
Build
2 min
Run
1 min
Push
1 min
Expired
trip ends
Request / flowResponse · the way backFailure / dead end

Try it: change the inputs and watch the trip bend

The budget bar above shows three fixed stories. This simulator lets you write your own. Move a slider and watch the build, the push, and the total change in the budget bar, in the hop timings, and in the total. The numbers are a teaching example, not live measurements. The shape is the lesson: more layers means a longer build, and an expired login costs a retry.

9

How many layers the Dockerfile builds. Each layer is one instruction, and a cold build downloads each one again.

80

How much of the build is cached. A warm cache skips the download. A cold cache downloads everything.

0

How many times the push is refused before someone runs docker login again. Each retry costs about 2 min.

Try this: (1) Set layers to 9, cache to 80%, logins to 0. The build is about 4 min, the push about 1 min, the run about 1 min, and the total is about 11 min. (2) Set all three to the worst end: 20 layers, 0% cache, 3 retries. The build is about 40 min, the push about 7 min, the run about 1 min, and the total is about 53 min. Same app. Only the inputs changed.

Check yourself

Three questions. No score is saved anywhere — this is just you against the material.

Try it: edit the pipeline and check it

Here is the Dockerfile from this lab, ready to edit. Change it, then run the check. The check looks for the five things a working Dockerfile needs: FROM, WORKDIR, COPY, RUN, and CMD.

Try breaking it on purpose: delete the FROM line, or move COPY . . above the RUN. Run the check and watch it fail. Then press Reset and try a change that keeps it passing, like adding a HEALTHCHECK line.

Press "Run the check" to see whether this pipeline does what the lesson asks.

Expected output when it passes: The Dockerfile has FROM, WORKDIR, COPY of the dependencies first, RUN npm ci, and CMD. The build would run, and the image would answer hello.

Basic to master

I take the same image four times here. First I write the app. Then I build it. Then I run it. Last I push it and pull it back.

Basic — The app first

Definition: An app is a program that answers on a port. server.js answers hello on port 3000. Proving the app works outside Docker first is the habit: if the app is broken, the image will be broken too, and the Dockerfile will take the blame.

Types:

  • server.js, which answers hello on port 3000.
  • node --check, which checks the file parses.
  • node --check, flag by flag. A syntax error in the server file is cheapest to find before the server starts. --check finds it without running anything.

    • --check parses the file and reports syntax errors without running it. Without it the first syntax error shows up only when the server starts, or worse, when a request hits the broken line.

    Flags you will meet next: -e runs code from the command line, and node server.js starts the server for real.

    Try it: run node --check server.js on a good file, then break one line on purpose and run it again. The first prints nothing and exits 0. The second prints the error and the line number.

  • curl, which proves the app answers.
  • A port, which is the door the app listens on.

Uses: I use this for any app I am about to containerise: run it bare first, curl it, then put it in an image. Try it now: run node server.js and curl it before you build anything.

Dimensions: At low volume everything is instant. What breaks first is the port: if another app already holds 3000, the new app cannot listen there.

Intermediate — The Dockerfile

Definition: A Dockerfile is a list of layers. FROM picks the base image. WORKDIR sets the folder. COPY copies files in. RUN runs a command. CMD says what runs when the container starts. Each line is one layer, and the cache remembers each one.

Types:

  • FROM, which picks the base image.
  • WORKDIR, which sets the folder inside the image.
  • COPY, which copies files in.
  • RUN and CMD, which build and start the app.

Uses: I use a Dockerfile whenever an app needs to run the same way on every machine. Try it now: write the lab Dockerfile and read it line by line.

Dimensions: As the app grows, the Dockerfile grows, and the layers multiply. What breaks is the order: code before dependencies means every code change rebuilds the dependencies.

Advanced — Build, run, curl

Definition: docker build turns the Dockerfile into an image. docker run turns the image into a container. docker ps lists the running containers. curl proves the container answers. The build log names the instruction that failed, and the curl answer is the proof the run worked.

Types:

  • docker build, which turns the file into an image.
  • docker images, which lists the images.
  • docker run, which turns the image into a container.
  • docker ps and curl, which prove the container runs and answers.

Uses: I use this loop for every image: build, run, curl, read the log when it fails. Try it now: build hello-lab, run it, and curl it.

Dimensions: At ten times the layers, the build is slower, and the cache matters more. What breaks is a cold cache: every layer downloads again, and the build takes ten times as long.

Master — Push and pull

Definition: At this level the image leaves your machine. docker tag gives it an address. docker login proves who you are. docker push puts it on the registry shelf. docker pull takes it down again, on any machine, and it answers the same way. Pulling proves the push worked.

Types:

  • docker tag, which gives the image an address.
  • docker login, which proves who you are.
  • docker push, which puts the image on the shelf.
  • docker pull, which takes it down again anywhere.

Uses: I use this when an image needs to run somewhere else: a server, a cluster, a teammate's laptop. Try it now: push hello-lab, pull it, and run it on a different port.

Dimensions: At a hundred images, the registry is the shelf, and the tags are the addresses. What breaks is a tag that moves: latest today is not latest tomorrow, and a deploy that pins latest deploys a surprise.

Go deeper

The app, the whole file. Do this: save it as server.js and run node --check server.js. Expected output: silence, which means it parses. Then run timeout 3 node server.js &, wait a second, and run curl -s http://localhost:3000/. Expected output: hello from the lab.

curl -s, flag by flag. One flag, one job: fetch the page and print it, with nothing extra.

  • -s hides the progress meter. Without it every run prints progress noise, and the real output gets buried in it.

Flags you will meet next: -o file saves the body to a file, and -I fetches headers only.

Try it: run it with -s and then without it. Without -s the progress meter prints to stderr, and the page is the same. The flag changes the noise, not the answer.

const http = require("http");
http.createServer((req, res) => { res.end("hello from the lab\n"); }).listen(3000);
console.log("listening on 3000");

The Dockerfile, the whole file. Do this: save it as Dockerfile and run docker build -t hello-lab:1.0.0 .. Expected output: one line per instruction, and the last line names the image. This file was checked line by line in this lab: every line starts with a known directive, and the first instruction is FROM.

docker build, flag by flag. The build reads the Dockerfile and stacks the layers. The flags name the image, pick the file, and pass values in.

  • -t names the image name:tag. Without it the image gets no name and no tag, and I cannot run it or push it by name.
  • . the build context: the folder Docker may copy files from. It is a path, not a flag, and it is required. A stray 2 GB file in that folder gets sent to the daemon on every build.

Flags you will meet next: --no-cache rebuilds every layer, and --platform linux/amd64 builds for a different CPU than the one you sit on.

Try it: build the same Dockerfile twice, once with -t app:1.0.0 and once with no -t at all. The first one you can run by name. The second one shows as <none>, and you cannot run it without its ID.

FROM node:20-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY . .
ENV NODE_ENV=production
USER node
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s CMD node -e "process.exit(0)" || exit 1
CMD ["node", "server.js"]

What the healthcheck means: Docker runs the command every 30 seconds, and if it fails, the container is marked unhealthy. Do this: run docker inspect hello --format '{{.State.Health.Status}}' after the container has run for a minute. Expected output: healthy. A container can be Up and unhealthy at the same time, and the healthcheck is how you tell.

docker inspect --format, flag by flag. inspect prints everything. --format prints one thing. I use the flag when I already know what I am looking for.

  • --format prints one value from the JSON instead of the whole document, using a Go template. Without it inspect prints pages of JSON, and the one field I want is somewhere in the middle.
  • {{.State.Health.Status}} the path inside the JSON. A wrong path prints an empty line, not an error, so I check the field name when the output is blank.

Flags you will meet next: {{json .Config.Env}} prints a whole block as JSON, and {{.Id}} prints the image ID alone.

Try it: run docker inspect with no --format and pipe it to wc -l, then run it with --format '{{.State.Health.Status}}'. The first prints hundreds of lines. The second prints one word: healthy, unhealthy, or starting.

Honest limit, stated plainly: this lab was verified by parsing the Dockerfile and running the app with node, not by running docker build. There is no Docker daemon in the machine this lab was written on, so no image was actually built here. The commands, the outputs, and the checks are the ones the reader runs on their own machine, where Docker Desktop is running. If a command fails there, the troubleshooting section below is the first place to look.

At 10x the images, the shape holds and the registry grows. At 100x, the design changes: the builds move into a pipeline, the images get scanned before they push, and the tags get pinned by digest. The order never changes, though. Deps first, code last.

One time it broke

What broke

A team pushed an image tagged latest every day, and the production deploy pulled latest every night. One night the image changed under the deploy: the code was new, the config was old, and the app failed to start. The deploy had pulled a different image than the one that was tested that morning, and nobody could say which image was running, because latest had moved.

Timeline

  • 09:00,the morning test passed on the image built that morning.
  • 17:00,a new image was pushed with the same tag, latest.
  • 02:00,the nightly deploy pulled latest, which was now the evening image, not the morning one.
  • 02:05,the app failed to start. The config in the evening image did not match the code.
  • 09:00,the team pinned the deploy to the digest of the tested image, and latest was banned from production.

What changed after

Two things. First, production deploys pin the image digest, never a moving tag. Second, every push tags the image with its version, 1.0.0, and latest is only a convenience for local work. Try it now: tag your image with 1.0.0 and check docker images shows the version, not just latest.

If you remember nothing else

Build it yourself

Build and run an image for an app you change yourself. It must build, run, answer curl, push to a registry, and pull back and answer again on a different port. It passes when the pulled image answers hello on the new port.

Build it, step by step

  • Change the greeting in server.js to your own words, and prove it answers outside Docker first.
  • Build the image with a version tag, not latest, and check docker images shows it.
  • Run it, curl it, and check docker ps shows it Up.
  • Push it to your registry, pull it back, and run it on a different port.
  • Stop and remove both containers, and confirm the image is still there.

What success looks like

Success looks like this: the image builds, the container answers your greeting on port 3000, the pulled image answers it on the new port, and docker images shows the version tag. If the pulled image answers the old greeting, you pulled the old tag.

If it fails, check this

If docker version shows no server, Docker Desktop is not running. If the build fails, read the last line of the log: it names the instruction. If curl fails, check the port mapping: host port first, container port second. If the push is refused, run docker login again. If the container exits at once, check the CMD: it must start a process that stays in the foreground.

Next in this series
Lesson 157 — Docker Lab: Compose a Whole App and Wire It by Name