Docker Image Development Fundamentals

Why It Matters

How it Works

The Philosophy of Immutable Infrastructure

In traditional software development, "it works on my machine" is a common failure mode. In MLOps, this problem is amplified by complex dependency chains involving CUDA, cuDNN, and specific versions of PyTorch or TensorFlow. Docker solves this by encapsulating the entire environment into an immutable image. Once an image is built, it is a static snapshot. If your model works inside the container on your laptop, it is mathematically guaranteed to work in the cloud, provided the underlying architecture (e.g., x86_64 vs ARM64) is consistent. This reliability is the bedrock of modern MLOps, allowing teams to treat infrastructure as code.

Layered Architecture and Caching

Docker images are constructed as a stack of layers. When you write a Dockerfile, every RUN, COPY, or ADD command creates a new layer. Docker caches these layers; if you change a line in your Dockerfile, Docker only rebuilds that layer and all subsequent ones. For ML practitioners, this is vital. Installing torch or scikit-learn takes minutes. By placing your requirements.txt copy and installation commands before copying your source code, you ensure that changing a single line of your model logic does not trigger a massive re-download of your ML dependencies. This optimization strategy can reduce build times from ten minutes to ten seconds.

Multi-Stage Builds for ML

ML models often require heavy build tools (like gcc or cmake) to compile custom C++ extensions for libraries like PyTorch or NumPy. However, these tools are unnecessary at runtime. Multi-stage builds allow you to use a "builder" image to install dependencies and compile code, and then copy only the necessary artifacts into a "slim" runtime image. This significantly reduces the attack surface of your container and lowers the storage footprint, which is critical when deploying models to edge devices or serverless environments like AWS Lambda or Google Cloud Run.

Managing GPU Dependencies

One of the most complex aspects of ML Docker development is GPU support. Unlike CPU-only containers, GPU containers require the NVIDIA Container Toolkit. Your Dockerfile must be compatible with the host's NVIDIA driver version. Using official NVIDIA CUDA base images is the industry standard. These images are pre-configured with the necessary libraries to interface with the GPU hardware. Failing to align the CUDA version in your image with the driver version on your production server will result in runtime errors that are notoriously difficult to debug.

Common Pitfalls

Sample Code

# Dockerfile for a scikit-learn inference service:
# FROM python:3.11-slim
# WORKDIR /app
# COPY requirements.txt .
# RUN pip install --no-cache-dir -r requirements.txt
# COPY train.py serve.py ./
# RUN python train.py          # bake model into image at build time
# CMD ["python", "serve.py"]

import joblib                          # correct serialiser for sklearn models
import numpy as np
from sklearn.linear_model import LinearRegression

def train_model():
    X = np.array([[1], [2], [3], [4], [5]])
    y = np.array([2, 4, 6, 8, 10])

    model = LinearRegression()
    model.fit(X, y)

    # joblib is the recommended way to persist sklearn objects
    # torch.save() only works with PyTorch tensors/modules, not sklearn
    joblib.dump(model, 'model.joblib')
    print("Model saved — coefficients:", model.coef_)

    loaded = joblib.load('model.joblib')
    print("Prediction for [[6]]:", loaded.predict([[6]]))

if __name__ == "__main__":
    train_model()
    # Model saved — coefficients: [2.]
    # Prediction for [[6]]: [12.]

Key Terms

Related Concepts