David Tio

Posted on May 25 • Originally published at blog.dtio.app

Customizing Docker Images: Write Your First Dockerfile (2026)

#docker #dockerfile #python #flask

Quick one-liner: Pre-built images are convenient until they break. A Dockerfile turns your app into a portable, reproducible artifact you can fix, rebuild, and own.

🤔 Why This Matters

In episode 10, we fixed the startup race. Ghost now waits for MySQL to be genuinely ready before starting. The stack is stable.

But after docker compose down --volumes, you rebuild from scratch: new theme, default config, all manual setup repeated. The image pulled from Docker Hub does not remember your changes.

That is not a Ghost problem. That is what it looks like when you do not own the image.

A Dockerfile is how you own it. You start from a base, install what you need, bake in configuration, and define exactly what runs when the container starts. The result is an artifact that rebuilds cleanly and consistently every time.

This episode covers the fundamentals: FROM, WORKDIR, COPY, RUN, EXPOSE, and CMD. The example is a Flask app — small enough to understand, realistic enough to matter.

✅ Prerequisites

Ep 1-10 completed. You are comfortable with Compose files, multi-service stacks, and health checks.

🗂 Project Structure

Create a working directory for this episode:

$ mkdir -p ~/noteboard
$ cd ~/noteboard

You will create three files:

noteboard/
├── app.py
├── requirements.txt
└── Dockerfile

✍️ The App

Create a minimal Flask app:

$ vi app.py

from flask import Flask

app = Flask(__name__)

@app.route("/")
def index():
    return "<h1>Noteboard</h1><p>Hello.</p>"

Create the requirements file — just Flask for now:

$ vi requirements.txt

flask==3.1.3

🐳 First Dockerfile: Flask Dev Server

Write your first Dockerfile:

$ vi Dockerfile

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
EXPOSE 5000
CMD ["flask", "run", "--host=0.0.0.0"]

Here is what each instruction does:

Instruction	What It Does
`FROM python:3.12-slim`	Start from the official Python 3.12 slim image — smaller footprint, versioned base
`WORKDIR /app`	Set the working directory inside the container. All following instructions run here
`COPY requirements.txt .`	Copy the requirements file from your host into `/app`
`RUN pip install ...`	Install dependencies at build time. This layer is cached until `requirements.txt` changes
`COPY app.py .`	Copy the app source code
`EXPOSE 5000`	Document that this container listens on port 5000
`CMD [...]`	The command that runs when the container starts

EXPOSE does not publish the port. It is documentation — a signal to whoever runs the image that port 5000 is where the app listens. You still need -p at runtime.

Build and run:

$ docker build -t noteboard .
$ docker run -d -p 5000:5000 --name noteboard noteboard

Test it:

$ curl http://localhost:5000

<h1>Noteboard</h1><p>Hello.</p>

It works. Now check the logs:

$ docker logs noteboard

 * Debug mode: off
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on all addresses (0.0.0.0)
 * Running on http://127.0.0.1:5000
 * Running on http://172.17.0.2:5000

That warning is not a style note. Flask's built-in server is single-threaded. It handles one request at a time. Under concurrent load it queues and drops connections. It is not designed to serve real traffic.

Stop the container before moving on:

$ docker stop noteboard && docker rm noteboard

🔧 Fix It: Switch to Gunicorn

Gunicorn is a production-grade WSGI server. It runs multiple worker processes, handles concurrent requests, and does not print warnings about being unsuitable for deployment.

Add it to requirements.txt:

$ vi requirements.txt

flask==3.1.3
gunicorn==22.0.0

Update the CMD in your Dockerfile:

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
EXPOSE 5000
CMD ["gunicorn", "--bind", "0.0.0.0:5000", "app:app"]

Rebuild and run:

$ docker build -t noteboard .
$ docker run -d -p 5000:5000 --name noteboard noteboard
$ docker logs noteboard

[2026-05-25 08:00:00 +0000] [1] [INFO] Starting gunicorn 22.0.0
[2026-05-25 08:00:00 +0000] [1] [INFO] Listening at: http://0.0.0.0:5000 (1)
[2026-05-25 08:00:00 +0000] [7] [INFO] Booting worker with pid: 7

No warning. One line change in the Dockerfile — that is what owning the image gives you.

One thing to notice about the ordering: requirements.txt is copied and installed before app.py. This is deliberate. Docker caches each layer. When you change app.py, Docker reuses the cached pip install layer and only rebuilds from COPY app.py onward. Reverse the order and every code change triggers a full reinstall.

🔨 Verify the Build

$ docker images noteboard

IMAGE              ID             DISK USAGE   CONTENT SIZE
noteboard:latest   a1b2c3d4e5f6        196MB         48.6MB

$ curl http://localhost:5000

<h1>Noteboard</h1><p>Hello.</p>

🔁 The Rebuild Workflow

Edit app.py to change the response:

@app.route("/")
def index():
    return "<h1>Noteboard</h1><p>Version 2.</p>"

Stop the running container, rebuild, and redeploy:

$ docker stop noteboard && docker rm noteboard
$ docker build -t noteboard .
$ docker run -d -p 5000:5000 --name noteboard noteboard
$ curl http://localhost:5000

On the second build, Docker reuses the cached install layer:

 => CACHED [4/5] RUN pip install --no-cache-dir -r requirements.txt
 => [5/5] COPY app.py .

Only the changed layers rebuild. This is why layer ordering matters.

🏷️ Tagging Your Builds

Every image you have built so far has been tagged latest. That is the default when you do not specify one. But latest is just a label — it has no special meaning. It does not mean newest, it does not update automatically. It is whatever you last tagged with it.

As your app evolves, version tags give you something latest cannot: the ability to know exactly what is running and to go back to a previous version if something breaks.

Tag your current build as 0.1:

$ docker build -t noteboard:0.1 .

Now edit app.py to mark the next release:

@app.route("/")
def index():
    return "<h1>Noteboard</h1><p>Version 1.0 — stable.</p>"

Build it as 1.0:

$ docker build -t noteboard:1.0 .

List both:

$ docker images noteboard

IMAGE              ID             DISK USAGE   CONTENT SIZE
noteboard:1.0      b2f3a4c5d6e7        196MB         48.6MB
noteboard:0.1      a1b2c3d4e5f6        196MB         48.6MB

Both images exist on your host. You can run either by name:

$ docker run -d -p 5000:5000 --name noteboard noteboard:1.0
$ curl http://localhost:5000

<h1>Noteboard</h1><p>Version 1.0 — stable.</p>

If 1.0 breaks something, switching back is one flag change:

$ docker stop noteboard && docker rm noteboard
$ docker run -d -p 5000:5000 --name noteboard noteboard:0.1

Stop the container before moving on:

$ docker stop noteboard && docker rm noteboard

✏️ Renaming an Image

Docker does not have a rename command. You rename an image by tagging it with the new name and removing the old tag.

Say you want to rename noteboard to myapp:

$ docker tag noteboard:1.0 myapp:1.0
$ docker rmi noteboard:1.0

docker tag creates a new name pointing at the same image layers — nothing is copied or rebuilt. docker rmi removes the old name. The underlying image data stays on disk as long as at least one tag points to it.

You can also use this to promote a tested version to latest:

$ docker tag noteboard:1.0 noteboard:latest

Now noteboard:latest and noteboard:1.0 both point to the same image. Pulling or running noteboard without a tag will use it.

🗄️ Baking Init Scripts into Database Images

The Flask example showed how to control what your app runs. Official database images go further — they provide a hook specifically for initialization.

Both MariaDB and Postgres run any .sql or .sh files placed in /docker-entrypoint-initdb.d/ on first startup. Drop your schema there and the database initializes itself. No manual connection, no migration script, no extra setup step.

Create a working directory:

$ mkdir -p ~/mariadb-custom
$ cd ~/mariadb-custom

Create the SQL file:

$ vi init.sql

CREATE TABLE notes (
    id INT AUTO_INCREMENT PRIMARY KEY,
    content TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

Write the Dockerfile:

$ vi Dockerfile

FROM mariadb:11
COPY init.sql /docker-entrypoint-initdb.d/

Build and run:

$ docker build -t mariadb-custom .
$ docker run -d \
    -e MARIADB_ROOT_PASSWORD=docker \
    -e MARIADB_DATABASE=appdb \
    --name mariadb-custom \
    mariadb-custom

Wait a few seconds for initialization, then verify the table was created:

$ docker exec -it mariadb-custom mariadb -uroot -pdocker appdb -e "SHOW TABLES;"

+------------------+
| Tables_in_appdb  |
+------------------+
| notes            |
+------------------+

Cleanup:

$ docker stop mariadb-custom && docker rm mariadb-custom

The table exists because the init script ran at first startup. Tear it down and bring it back up — the schema is part of the image, not a step you repeat.

🧪 Exercise 1: Auto-Initialize a Postgres Schema

Postgres supports the same /docker-entrypoint-initdb.d/ hook as MariaDB. Apply the same pattern using a Postgres image.

Create the project folder:

$ mkdir -p ~/pgcustom
$ cd ~/pgcustom

Create the SQL file:

$ vi init.sql

CREATE TABLE notes (
    id SERIAL PRIMARY KEY,
    content TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

Write the Dockerfile:

$ vi Dockerfile

FROM postgres:16
COPY init.sql /docker-entrypoint-initdb.d/

Build and run:

$ docker build -t pgcustom .
$ docker run -d \
    -e POSTGRES_PASSWORD=docker \
    -e POSTGRES_DB=appdb \
    --name pgcustom \
    pgcustom

Wait a few seconds, then verify the table was created:

$ docker exec -it pgcustom psql -U postgres -d appdb -c "\dt"

        List of relations
 Schema | Name  | Type  |  Owner
--------+-------+-------+----------
 public | notes | table | postgres

Cleanup:

$ docker stop pgcustom && docker rm pgcustom

The schema was created at first startup — no manual psql session, no migration script, just a COPY instruction in the Dockerfile.

🧪 Exercise 2: Bake a Custom Theme into a Ghost Image

In episode 10, you ran Ghost with health checks. But after docker compose down --volumes, Ghost starts fresh — database wiped, any configuration you applied through the UI gone.

In this exercise, you will modify Ghost's default theme directly in the image. The change is visible the moment Ghost starts — no admin registration, no theme activation, no re-uploading after teardown.

Ghost ships with a theme called source that is active by default. Its templates live at /var/lib/ghost/current/content/themes/source/. Replacing default.hbs in your Dockerfile replaces it in the image layer — Ghost loads your version on every startup.

Create a fresh project folder:

$ mkdir -p ~/ghost-custom
$ cd ~/ghost-custom

Create config.production.json:

$ vi config.production.json

{
  "url": "http://localhost:2368",
  "server": {
    "host": "::",
    "port": 2368
  },
  "database": {
    "client": "mysql",
    "connection": {
      "host": "db",
      "user": "ghost",
      "password": "ghostpass",
      "database": "ghost",
      "port": 3306
    }
  },
  "mail": {
    "transport": "SMTP",
    "options": {
      "host": "mail",
      "port": 1025
    }
  }
}

Extract the original default.hbs from the Ghost image:

$ docker run --rm ghost:5-alpine \
    cat /var/lib/ghost/current/content/themes/source/default.hbs > default.hbs

Edit it to add a banner. Find the <div class="gh-viewport"> line and add the banner immediately after it:

$ vi default.hbs

 <div class="gh-viewport">
+
+    <div style="background:#0f766e;color:white;text-align:center;padding:0.75rem;font-size:0.9rem;font-family:sans-serif;">
+        Running on a custom Ghost image — theme baked in at build time.
+    </div>
+
     {{> "components/navigation" navigationLayout=@custom.navigation_layout}}

Write the Dockerfile:

$ vi Dockerfile

FROM ghost:5-alpine
COPY config.production.json /var/lib/ghost/config.production.json
COPY default.hbs /var/lib/ghost/current/content/themes/source/default.hbs

Build the image:

$ docker build -t ghost-custom .

Create the Compose file:

$ vi docker-compose.yml

services:
  db:
    image: mysql:8
    environment:
      MYSQL_ROOT_PASSWORD: rootpass
      MYSQL_DATABASE: ghost
      MYSQL_USER: ghost
      MYSQL_PASSWORD: ghostpass
    healthcheck:
      test: ["CMD-SHELL", "mysqladmin ping -h localhost -ughost -pghostpass --silent"]
      interval: 5s
      timeout: 3s
      retries: 12
      start_period: 10s

  mail:
    image: axllent/mailpit:latest
    ports:
      - "8025:8025"

  app:
    image: ghost-custom
    ports:
      - "2368:2368"
    depends_on:
      db:
        condition: service_healthy
      mail:
        condition: service_started

Bring it up:

$ docker compose up -d

Visit http://localhost:2368. The teal banner appears at the top.
Now tear it down and bring it back:

$ docker compose down --volumes
$ docker compose up -d

Visit http://localhost:2368 again. The banner is still there.

The database was wiped. The theme modification was not — it is part of the image.

🏁 What You Built

What	Why It Matters
`FROM python:3.12-slim`	Starts from a clean, versioned base instead of inheriting unknown state
`WORKDIR`	Sets a predictable working directory — no scattered files across the container filesystem
Layer ordering	`requirements.txt` before `app.py` — expensive installs are cached; only changed code rebuilds
Gunicorn instead of dev server	Removes the dev server warning and makes the app production-capable
`/docker-entrypoint-initdb.d/` hook	Schema baked into database images — first startup initializes without manual intervention, works on both MariaDB and Postgres
Version tags (`0.1`, `1.0`)	Each build is addressable — you know what is running and can roll back without rebuilding
Modified source theme baked into Ghost image	Change is visible immediately at startup — no registration, no theme activation, survives `down --volumes`

Coming up: You built two images this episode. Both work. Neither is reachable without a port number in the URL. How many of your users are typing :2368? Next episode, we fix that.

DEV Community