Build and run a small Python web app in a container

What you will build

A web page served by a small Python (Flask) application that runs inside a Docker container. You will write the app, describe its image in a Dockerfile, build the image, run it on port 8000, look at its logs, change the code and rebuild, and finally remove everything. By the end you will have used the handful of commands that cover most daily Docker work.

Before you start

• Docker installed and working: docker run hello-world prints a greeting. On Linux see the entry on installing Docker Engine; on macOS and Windows use Docker Desktop.
• A terminal and a text editor. No Python installation is needed on your machine; Python runs inside the container.
• About 20 minutes and roughly 200 MB of disk for the base image.

Step 1: Create the project folder and the app

mkdir hello-container
cd hello-container

Create app.py:

import os
import socket

from flask import Flask

app = Flask(__name__)


@app.get("/")
def index():
    name = os.environ.get("GREETING_NAME", "world")
    return f"<h1>Hello, {name}!</h1><p>Served from container {socket.gethostname()}</p>"


@app.get("/health")
def health():
    return {"status": "ok"}


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8000)

Two things matter for containers here. The app listens on 0.0.0.0, not 127.0.0.1: inside the container, localhost is the container itself, and Docker’s port forwarding only reaches a process bound to all interfaces. And configuration comes from an environment variable, which is how containers are usually configured.

Create requirements.txt with the one dependency:

flask

Step 2: Write the Dockerfile

Create a file named exactly Dockerfile (no extension):

FROM python:3.13-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app.py .

RUN useradd --create-home appuser
USER appuser

EXPOSE 8000
CMD ["python", "app.py"]

• FROM python:3.13-slim: start from the official Python image, the slim variant without build tools.
• WORKDIR /app: all following paths are relative to /app inside the image.
• Dependencies are installed before the source is copied, so editing app.py later does not re-run pip install.
• USER appuser: the app runs as a normal user, not root.
• CMD: the command the container runs when it starts.

Also create .dockerignore so stray files never end up in the image:

__pycache__
*.pyc
.git

Step 3: Build the image

docker build -t hello-container:1.0 .
docker image ls hello-container

The final . is the build context: the folder whose files COPY may use. The first build downloads the base image and installs Flask; expect a minute or so. -t names the image. The listing shows an image of a bit over 100 MB.

Step 4: Run the container

docker run -d --name hello -p 8000:8000 hello-container:1.0
docker ps

Open http://localhost:8000 in a browser, or from the terminal:

curl http://localhost:8000
curl http://localhost:8000/health

You should see the greeting with a hostname that looks like 3f1c9a2b7d4e. That is the container’s ID: each container gets its own hostname.

Step 5: Look at logs and get a shell inside

docker logs hello
docker exec -it hello sh
ls -la /app
whoami
exit

logs shows Flask’s request log. exec -it ... sh opens a shell in the running container; whoami prints appuser, confirming the USER instruction worked.

Step 6: Change the configuration without rebuilding

docker rm -f hello
docker run -d --name hello -p 8000:8000 -e GREETING_NAME=Docker hello-container:1.0
curl http://localhost:8000

The page now says Hello, Docker. Settings that differ between environments belong in environment variables, so the same image runs everywhere.

Step 7: Change the code and rebuild

Edit app.py and change the <h1> text, then build a new version and replace the running container:

docker build -t hello-container:1.1 .
docker rm -f hello
docker run -d --name hello -p 8000:8000 hello-container:1.1
curl http://localhost:8000

This build is much faster: every layer up to COPY app.py came from the cache. Both 1.0 and 1.1 exist locally now, so rolling back is just running the old tag again.

Check that it works

• docker ps lists hello with status Up and ports 0.0.0.0:8000->8000/tcp.
• curl http://localhost:8000/health returns {"status":"ok"}.
• docker logs hello shows a line for each request you made.
• docker exec hello whoami prints appuser.

Clean up

docker rm -f hello
docker rmi hello-container:1.0 hello-container:1.1
docker image ls

The project folder stays; only the container and your two images are removed. Careful: docker rmi deletes the images, so rebuild with docker build if you want them back. You can also remove python:3.13-slim with docker rmi python:3.13-slim if you do not plan to build again.

Next steps

• Add a database and run both with Compose: see the entry on docker compose for an app with a PostgreSQL database.
• Replace Flask’s development server with a production server such as gunicorn in the CMD.
• Push the image to a registry so you can run it on another machine: see the entry on tagging, pushing and pulling images.
• Read the Dockerfile entry for ENTRYPOINT, multi-stage builds and cache ordering.

Official documentation

• Docker: Get started
• Dockerfile reference
• Flask quickstart