Containers and deployment

Configuration from the environment

A touring band plays the same songs in every city, and only the venue changes. The same image should run in development, staging and production. What differs, like database addresses, keys and log levels, comes from environment variables. This is one of the twelve-factor app rules.

Read and check all settings at start-up. A missing database address should stop the app at once with a clear message, not crash on the first request at 3 a.m. Secrets come from the platform's secret store and arrive as environment variables or mounted files, never baked into the image.

Health checks and shutdown

Platforms ask your app two questions:

• Liveness (/healthz): is the process alive? If not, restart it.
• Readiness (/readyz): can it serve traffic now? Database reachable, caches warmed? If not, send no traffic yet, but don't restart it.

When stopping a container, the platform sends SIGTERM, which works like last orders at a bar. Stop accepting new requests, finish the ones in progress, then exit. After a grace period it sends SIGKILL.

def liveness(state):
    return 200 if state["process_ok"] else 500

def readiness(state):
    return 200 if state["process_ok"] and state["database_ok"] and not state["shutting_down"] else 503

scenarios = {
    "normal": {"process_ok": True, "database_ok": True, "shutting_down": False},
    "database down": {"process_ok": True, "database_ok": False, "shutting_down": False},
    "shutting down": {"process_ok": True, "database_ok": True, "shutting_down": True},
    "deadlocked": {"process_ok": False, "database_ok": True, "shutting_down": False},
}
for name, state in scenarios.items():
    print(f"{name:<14} live {liveness(state)}  ready {readiness(state)}")

Rolling out

There's more than one way to swap in a new version. You can change a car's tires one at a time. You can set up a second stage, then move the audience across. Or you can do what miners did, and send a canary in first to see whether the air is safe:

Whatever the strategy, rollback should be one action: deploy the previous image tag. Database changes need care, since old code must still work with the new schema during the rollout.

In plain words: expect some releases to go wrong, and make going back the easiest thing you can do.

Platforms range from simple (Railway, Render, Fly.io, Google Cloud Run: give them an image) to powerful (Kubernetes: you describe deployments, services and replicas, and it keeps them running).

def decide(old_errors, old_total, new_errors, new_total, min_requests=500, margin=2.0):
    if new_total < min_requests:
        return "wait: not enough traffic yet"
    old_rate, new_rate = old_errors / old_total, new_errors / new_total
    if new_rate > max(old_rate * margin, 0.001):
        return f"roll back: {new_rate:.2%} against {old_rate:.2%}"
    return f"promote: {new_rate:.2%} against {old_rate:.2%}"

print(decide(50, 10000, 1, 40))
print(decide(50, 10000, 9, 600))
print(decide(50, 10000, 3, 600))

env = {"PORT": "8080", "ENABLE_CACHE": "yes"}

port = int(env.get("PORT", "8000"))
cache = env.get("ENABLE_CACHE", "false").lower() in ("1", "true", "yes")
log_level = env.get("LOG_LEVEL", "info")
print(port, cache, log_level)
print(type(env["PORT"]).__name__, "->", type(port).__name__)

env = {"ENABLE_CACHE": "False"}
print(bool(env["ENABLE_CACHE"]), env["ENABLE_CACHE"].lower() in ("1", "true", "yes"))

Mistakes that come back to bite

Don't use latest for base images. FROM python:latest gives you a different image from one week to the next, so a build that worked on Monday can fail on Thursday with no code change. Pin the version, such as python:3.14-slim.

Keep secrets out of ENV lines. Everything in a Dockerfile is saved in the image's layers, and anyone who can pull the image can read them. Pass secrets in at run time from your platform's secret store.

Don't restart because of the database. If liveness checks your database, an outage there makes the platform restart all your healthy servers, over and over. That's why database checks belong in readiness.

Read your configuration at startup. If a required setting is missing, the app should crash straight away with a clear message. Reading it on first use means the deploy looks healthy, and then it fails hours later on the first real request.