dockerflow

2026.3.4 verified Fri May 01 auth: no python

Python tools and helpers for implementing Mozilla's Dockerflow standards, providing health check endpoints (__version__, __heartbeat__, __lbheartbeat__), structured logging (MozLog), and framework integrations for Django, Flask, FastAPI, Sanic, and others. Current version: 2026.3.4. Active development with monthly/quarterly releases.

pip install dockerflow

Common errors

error ImportError: cannot import name 'DjangoDockerflow' from 'dockerflow' ↓

cause Old documentation or code snippets refer to a non-existent class.

fix

Use from dockerflow.django import DockerflowMiddleware, dockerflow_view instead.

error AttributeError: module 'dockerflow' has no attribute 'checks' ↓

cause Importing the top-level package without importing the submodule.

fix

Explicitly import from dockerflow import checks.

error RuntimeError: Unable to find a DockerflowView: No view named 'dockerflow' ↓

cause Django project missing the dockerflow view URL configuration.

fix

Add URL pattern: path('__version__', dockerflow_view, name='dockerflow-version') and ensure middleware is added.

error fastapi.exceptions.FastAPIError: Invalid args for response status code ↓

cause Using FastAPI router with a prefix like '/dockerflow' which conflicts with the pre-defined endpoint paths.

fix

Include router with prefix='' or no prefix: app.include_router(router).

Warnings

gotcha Heartbeat returns 200 even when checks issue warnings (only 5xx for errors). Reading docstrings incorrectly can lead to expecting 5xx on warnings. ↓

fix Treat warning results as 200 OK; only error results cause 5xx. See https://github.com/mozilla-services/python-dockerflow/issues/110

gotcha In Django, you must add 'dockerflow.django.middleware.DockerflowMiddleware' to MIDDLEWARE and mount the view yourself. The old `urlpatterns += [path(...)]` pattern is outdated in some docs. ↓

fix Add middleware and define the view URL pattern explicitly: path('__version__', dockerflow_view, name='dockerflow-version')

deprecated The `default_app_config` in Django apps is removed in django>3.2 and not needed for dockerflow. ↓

fix Remove `default_app_config` from any Django app config; it has no effect and may cause deprecation warnings.

gotcha When using FastAPI, the dockerflow router must be included with prefix='', or endpoints will be duplicated. Incorrect prefix leads to 404 on heartbeat endpoints. ↓

fix Include router as `app.include_router(router)` without prefix (defaults to '').

Install

pip install dockerflow[django]

pip install dockerflow[flask]

pip install dockerflow[fastapi]

Imports

checks
wrong
```
from dockerflow.checks import *
```
correct
```
from dockerflow import checks
```
Import the module, not individual check functions; use register_check instead.

Django

wrong

from dockerflow import DjangoDockerflow

correct

from dockerflow.django import DockerflowMiddleware, dockerflow_view

The Django integration uses a specific middleware and view; no class named DjangoDockerflow.

FastAPI

wrong

from dockerflow import FastAPIRouter

correct

from dockerflow.fastapi import router

FastAPI integration provides a router object, not a class.

Flask
```
from dockerflow.flask import Dockerflow
```
Used as an extension: Dockerflow(app). No common wrong import known.

Quickstart

Minimal Flask app with dockerflow endpoints (__version__, __heartbeat__, __lbheartbeat__) and a custom check.

from dockerflow import checks
from dockerflow.flask import Dockerflow
from flask import Flask

app = Flask(__name__)
dockerflow = Dockerflow(app)

@checks.register('storage')
def storage_check(config):
    if not some_storage_available():
        return [checks.Error('storage unavailable')]
    return []

@app.route('/')
def index():
    return 'OK'

if __name__ == '__main__':
    app.run()