Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 41 ยท Model Packaging and Registry

Containerizing a Model

Learn how to package a model service in a Docker image, write a lean Dockerfile with cached layers, add a health check and non-root user, and verify the container before you ship it.

A container image freezes the whole runtime: the operating system layer, system libraries, Python, your pinned packages, the model file and the start command. The same image runs the same way on a laptop, in CI and in production, which removes most "works on my machine" surprises left over after pinning dependencies.

This site cannot run Docker inside a page, so the Dockerfiles below are read-only. The Python examples run for real and check the things a good container needs: a health endpoint and a clean start-up check. For hands-on Docker, see the Docker tutorial.

A Dockerfile for a model service

DOCKERFILE
FROM python:3.12-slim

# system settings: no .pyc files, unbuffered logs
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1

WORKDIR /app

# 1. dependencies first: this layer is cached until requirements change
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 2. then code and model: these change more often
COPY app/ app/
COPY model/ model/

# run as a normal user, not root
RUN useradd --create-home appuser
USER appuser

EXPOSE 8000
HEALTHCHECK --interval=30s --timeout=3s CMD python -c "import urllib.request as u; u.urlopen('http://127.0.0.1:8000/health')"

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Build and run it with docker build -t churn-service:1.0.0 . and docker run -p 8000:8000 churn-service:1.0.0.

A good model image

Small Slim base, no build tools.
Cached Dependencies before code.
Safe Non-root user, no secrets.
Healthy Health check built in.

Fast to pull, quick to start, hard to abuse.

1 / 2

Why the order of layers matters

Docker caches each instruction as a layer. If COPY requirements.txt and pip install come before copying your code, changing one line of code does not re-install every library. Put the slow, rarely changing steps first. Add a .dockerignore file listing data/, .git/, notebooks and virtual environments so they never enter the build.

Model inside the image or outside?

Approach Good Bad
Bake the model into the image Self-contained, one artifact to version, simple rollbacks New image for each model version; larger images
Download at start-up from the registry or object storage One image, many models; models update independently Slower start, needs credentials and network, can fail at boot

For small models, baking in is simplest and safest: the image tag is the model version. Large models are often fetched at start-up with a checksum check.

A start-up check you can run

A container should fail fast when something is wrong, so the orchestrator does not send it traffic. This example checks a model and a version list the way an entry script would.

Python Fail fast at start-up

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Health and readiness

Orchestrators such as Kubernetes distinguish two checks:

  • Liveness ("is the process alive?"): if it fails, restart the container.
  • Readiness ("can it serve traffic now?"): if it fails, stop routing requests to it. A model still loading should be not ready.
Python Readiness versus liveness

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Practical advice

  • Tag with the model version plus the Git commit, for example churn-service:1.4.0-abc1234; never deploy latest.
  • Scan images for known vulnerabilities in CI.
  • Pin the base image to a version (or digest), and rebuild regularly for security fixes.
  • Use multi-stage builds when you need compilers to build wheels but do not want them in the final image.
  • Set resource limits (CPU, memory) so one container cannot starve others; see latency and throughput.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why copy requirements.txt and install before copying the application code?

    Layers are cached top to bottom; putting rarely changing steps first avoids re-installing libraries on every code edit.
  2. 2. What is a downside of baking a large model into the image?

    Large models make images heavy to build and pull; fetching at start-up trades that for boot-time dependencies.
  3. 3. What should a readiness check report while the model is still loading?

    Not ready keeps requests away until the model is loaded; liveness failures restart the container.
  4. 4. Why avoid the 'latest' tag in production?

    Specific tags tie an image to a model and commit, making rollbacks exact.

Summary

  • A container image freezes OS libraries, Python packages, code and (optionally) the model.
  • Order layers from least to most frequently changing; use .dockerignore, a slim base and a non-root user.
  • Decide deliberately between baking the model in or fetching it at start-up.
  • Fail fast at start-up, expose liveness and readiness, and tag images with versions, never latest.

Next: CI/CD for Machine Learning