A prediction API is not fully deployable merely because it runs inside the development environment. The operating system, Python runtime, dependencies, application code, and model artifact must reach the target environment together. A container image packages those components into one versioned unit.
This chapter containerizes the FastAPI service developed in Serving Predictions with FastAPI and tested in Validation, Errors, and API Testing. The objective is not simply to make Docker run. It is to create a small, inspectable image whose behaviour can be verified before it is released.
By the end of this chapter, you should be able to:
Dockerfile for a FastAPI service;The container workflow has two distinct phases. docker build creates an immutable image from the project files and instructions. docker run starts an isolated process from that image.
flowchart TD
A["Application, model, and dependencies"] --> B["Docker build context"]
B --> C["Versioned image"]
C --> D["Running container"]
D --> E["Health and prediction checks"]flowchart TD
A["Application, model, and dependencies"] --> B["Docker build context"]
B --> C["Versioned image"]
C --> D["Running container"]
D --> E["Health and prediction checks"]
An image is a packaged template. A container is a running instance of that template. Several containers can be started from the same image, but runtime changes inside one container do not update the image.
Complete the API implementation and tests before containerizing it. At minimum, the repository should contain:
model-deployment/
├── app/
│ ├── __init__.py
│ └── main.py
├── models/
│ └── deployment_pipeline.joblib
├── scripts/
│ ├── bash/
│ └── python/
├── requirements.txt
├── Dockerfile
└── .dockerignoreThe examples assume that the FastAPI object is named app in app/main.py, giving the import string app.main:app. If your module differs, change that string consistently in the Dockerfile and local commands.
Confirm that Docker is available:
docker --version
docker infodocker --version confirms that the client is installed. docker info also checks whether the Docker engine is running.
The container must install the packages required at runtime. A focused deployment file avoids pulling notebook and development tools into the image. For a small guide project, the existing requirements.txt may be used if it already contains the following runtime dependencies:
fastapi
joblib
numpy
pandas
pydantic
scikit-learn
uvicorn[standard]Pinning exact versions in requirements-lock.txt improves reproducibility. When a tested lock file exists, substitute it for requirements.txt in the Dockerfile. Do not generate a lock file from an unrelated virtual environment.
At the repository root, create Dockerfile:
FROM python:3.12-slim
ENV PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1 \
PIP_NO_CACHE_DIR=1
WORKDIR /app
COPY requirements.txt ./
RUN python -m pip install --upgrade pip \
&& python -m pip install -r requirements.txt
COPY app/ ./app/
COPY models/ ./models/
RUN useradd --create-home --uid 10001 apiuser \
&& chown -R apiuser:apiuser /app
USER apiuser
EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]Each instruction has a specific deployment purpose:
| Instruction | Purpose |
|---|---|
FROM python:3.12-slim |
Starts from a compact Python runtime. |
WORKDIR /app |
Makes application paths predictable inside the image. |
COPY requirements.txt before source code |
Allows Docker to reuse the dependency layer when only application code changes. |
COPY app/ and COPY models/ |
Includes only the runtime code and trained artifact. |
USER apiuser |
Avoids running the service as the root user. |
EXPOSE 8000 |
Documents the port used by the application. |
--host 0.0.0.0 |
Makes Uvicorn reachable outside the container. |
EXPOSE documents the intended container port; it does not publish that port to the host. Port publishing happens when the container is started.
Docker sends the build context to the builder. A .dockerignore file prevents irrelevant, large, or sensitive files from entering that context.
.git
.gitignore
.venv
__pycache__
*.py[cod]
.pytest_cache
.ipynb_checkpoints
.DS_Store
docs
notebooks
reports
results
tests
*.log
.env
.env.*Do not exclude models/ when the application loads its model from that directory. Never bake credentials or production secrets into the image. Supply runtime configuration through the deployment platform or environment variables.
From the repository root, run:
docker build --tag cdi-model-api:07 .The final period selects the current directory as the build context. The explicit tag identifies both the application and the chapter-stage version.
Inspect the result:
docker image ls cdi-model-api
docker image inspect cdi-model-api:07A successful build proves that the image instructions completed. It does not prove that the service starts correctly or returns valid predictions.
Start the service in the background:
docker run \
--detach \
--name cdi-model-api-07 \
--publish 8000:8000 \
cdi-model-api:07The mapping 8000:8000 means host-port:container-port. The API should now be available at http://127.0.0.1:8000.
Check its state and logs:
docker ps --filter name=cdi-model-api-07
docker logs cdi-model-api-07
curl --fail --silent http://127.0.0.1:8000/healthThen run the Chapter 06 contract checks against the containerized service:
bash scripts/bash/06-test-api.shThe same tests should pass whether Uvicorn runs from the virtual environment or inside a container. That equivalence is important: containerization should change packaging, not the API contract.
The companion script builds the image, starts a temporary container, waits for the health endpoint, runs the Chapter 06 API test script when it is available, and removes the container on exit:
bash scripts/bash/07-build-and-test-container.shOptional environment variables allow the defaults to be changed without editing the script:
IMAGE_NAME=cdi-model-api \
IMAGE_TAG=07 \
HOST_PORT=8001 \
bash scripts/bash/07-build-and-test-container.shThe script deliberately removes only the container it creates. It does not delete the resulting image, so the verified artifact remains available for inspection or later use.
An HTTP health endpoint is useful only when the runtime checks it. Python is already present in the image, so a health check can avoid adding another system package. Add the following instruction before CMD:
HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health', timeout=2)" || exit 1Rebuild and run the image, then inspect its status:
docker inspect \
--format='{{json .State.Health}}' \
cdi-model-api-07The endpoint should confirm that the process can serve requests. If prediction readiness depends on a loaded model, the health logic should also verify that the artifact was loaded successfully.
Use read-only inspection when debugging the packaged files:
docker run --rm cdi-model-api:07 \
python -c "from app.main import app; print(app.title)"To list the model artifact without opening an interactive shell:
docker run --rm cdi-model-api:07 \
python -c "from pathlib import Path; print(list(Path('models').glob('*')))"These checks answer two frequent questions: whether the Python module can be imported and whether the model artifact is present at the path expected by the application.
When a manually started container is no longer needed:
docker stop cdi-model-api-07
docker rm cdi-model-api-07Stopping ends the process; removing deletes that container instance. The image remains available. To remove the image later, first confirm that it is no longer needed:
docker image rm cdi-model-api:07Map a different host port while leaving the container port unchanged:
docker run --rm --publish 8001:8000 cdi-model-api:07The service is then available at http://127.0.0.1:8001.
Inspect all containers and read the logs:
docker ps --all --filter name=cdi-model-api-07
docker logs cdi-model-api-07Common causes include an invalid import string, a missing package, or a model-loading exception during application startup.
Relative paths depend on the container working directory. Resolve model paths from the application module or from the known /app working directory, and confirm that .dockerignore does not exclude the artifact.
Confirm that Uvicorn binds to 0.0.0.0, the correct port is published, and the request is sent to the host-side port. Binding to 127.0.0.1 inside the container makes the service unreachable from the host.
Inspect its layers:
docker history cdi-model-api:07Use a slim base image, exclude development files, avoid copying the entire repository, and keep build-only tools out of the final runtime image.
Before treating the image as a deployment candidate, confirm that:
latest;Containerization improves environmental consistency, but it does not validate the model, secure the surrounding platform, or monitor prediction quality. Those responsibilities remain part of the wider deployment system.
A deployment-ready container is more than a successful docker build. It is a reproducible package containing the required runtime, dependencies, application, and model artifact. Its service must start under container constraints and satisfy the same validated API contract established before packaging.
The workflow is therefore:
The next chapter can build on this verified image by adding configuration, release, and operational deployment practices.