Skip to content

Environment variables

Usage

To set environment variables when starting a Docker container:

docker run -d -p 80:80 \
  -e APP_MODULE="package.custom.module:api" \
  -e WORKERS_PER_CORE="2" \
  myimage

To set environment variables within a Dockerfile:

FROM ghcr.io/br3ndonland/inboard:fastapi
ENV APP_MODULE="package.custom.module:api" WORKERS_PER_CORE="2"

General

APP_MODULE

  • Python module with app instance.
  • Default: The appropriate app module from inboard.

  • Custom: For a module at /app/package/custom/module.py and app instance object api, APP_MODULE="package.custom.module:api"

    Example of a custom FastAPI app module

    # /app/package/custom/module.py
from fastapi import FastAPI

api = FastAPI()

@api.get("/")
def read_root():
    return {"message": "Hello World!"}

    Note

    The base Docker image sets the environment variable PYTHONPATH=/app, so the module name will be relative to /app unless you supply a custom PYTHONPATH.

PRE_START_PATH

  • Path to a pre-start script.
  • Default: "/app/inboard/prestart.py" (provided with inboard)

  • Custom:

    • PRE_START_PATH="/app/package/custom_script.sh"
    • PRE_START_PATH= (set to an empty value) to disable

    Tip

    Add a file prestart.py or prestart.sh to the application directory, and copy the directory into the Docker image as described (for a project with the Python application in repo/package, COPY package /app/package). The container will automatically detect and run the prestart script before starting the web server.

PYTHONPATH

  • Python's search path for module files.
  • Default: PYTHONPATH="/app"
  • Custom: PYTHONPATH="/app/custom"

Gunicorn

Configuration file

GUNICORN_CONF

  • Path to a Gunicorn configuration file. The Gunicorn command-line accepts file paths instead of module paths.
  • Default:
    • "/app/inboard/gunicorn_conf.py" (provided with inboard)
  • Custom:
    • GUNICORN_CONF="/app/package/custom_gunicorn_conf.py"

Process management

Info

As described in the Uvicorn docs, "Uvicorn includes a Gunicorn worker class allowing you to run ASGI applications, with all of Uvicorn's performance benefits, while also giving you Gunicorn's fully-featured process management."

PROCESS_MANAGER

  • Manager for Uvicorn worker processes.
  • Default: "gunicorn" (run Uvicorn with Gunicorn as the process manager)
  • Custom: "uvicorn" (run Uvicorn alone for local development)

WORKER_CLASS

  • Uvicorn worker class for Gunicorn to use.
  • Default: uvicorn.workers.UvicornWorker
  • Custom: For the alternate Uvicorn worker, WORKER_CLASS="uvicorn.workers.UvicornH11Worker" (the H11 worker is provided for PyPy and hasn't been tested)

Worker process calculation

Info

The number of Gunicorn worker processes to run is determined based on the MAX_WORKERS, WEB_CONCURRENCY, and WORKERS_PER_CORE environment variables, with a default of 1 worker per CPU core and a default minimum of 2. This is the "performance auto-tuning" feature described in tiangolo/uvicorn-gunicorn-docker.

MAX_WORKERS

  • Maximum number of workers, independent of number of CPU cores.
  • Default: not set (unlimited)
  • Custom: MAX_WORKERS="24"

WEB_CONCURRENCY

  • Total number of workers, independent of number of CPU cores.
  • Default: not set
  • Custom: WEB_CONCURRENCY="4"

WORKERS_PER_CORE

  • Number of Gunicorn workers per CPU core. Overridden if WEB_CONCURRENCY is set.
  • Default: 1

  • Custom:

    • WORKERS_PER_CORE="2": Run 2 worker processes per core (8 worker processes on a server with 4 cores).
    • WORKERS_PER_CORE="0.5" (floating point values permitted): Run 1 worker process for every 2 cores (2 worker processes on a server with 4 cores).

    Note

    • The default number of workers is the number of CPU cores multiplied by the value of the environment variable WORKERS_PER_CORE (which defaults to 1). On a machine with only 1 CPU core, the default minimum number of workers is 2 to avoid poor performance and blocking, as explained in the release notes for tiangolo/uvicorn-gunicorn-docker 0.3.0.
    • If both MAX_WORKERS and WEB_CONCURRENCY are set, the least of the two will be used as the total number of workers.
    • If either MAX_WORKERS or WEB_CONCURRENCY are set to 1, the total number of workers will be 1, overriding the default minimum of 2.

Worker timeouts

GRACEFUL_TIMEOUT

  • Number of seconds to wait for workers to finish serving requests before restart.
  • Default: "120"
  • Custom: GRACEFUL_TIMEOUT="20"

TIMEOUT

  • Workers silent for more than this many seconds are killed and restarted.
  • Default: "120"
  • Custom: TIMEOUT="20"

KEEP_ALIVE

  • Number of seconds to wait for workers to finish serving requests on a Keep-Alive connection.
  • Default: "5"
  • Custom: KEEP_ALIVE="20"

Host networking

HOST

  • Host IP address (inside of the container) where Gunicorn will listen for requests.
  • Default: "0.0.0.0"
  • Custom: n/a

PORT

  • Port the container should listen on.
  • Default: "80"
  • Custom: PORT="8080"

BIND

  • The actual host and port passed to Gunicorn.
  • Default: HOST:PORT ("0.0.0.0:80")
  • Custom: BIND="0.0.0.0:8080" (if custom BIND is set, overrides HOST and PORT)

Runtime configuration

GUNICORN_CMD_ARGS

  • Additional command-line arguments for Gunicorn. Gunicorn looks for the GUNICORN_CMD_ARGS environment variable automatically, and gives these settings precedence over other environment variables and Gunicorn config files.

  • Custom: To use a custom TLS certificate, copy or mount the certificate and private key into the Docker image, and set --keyfile and --certfile to the location of the files.

    CERTS="--keyfile=/secrets/key.pem --certfile=/secrets/cert.pem"
docker run -d -p 443:443 \
  -e GUNICORN_CMD_ARGS="$CERTS" \
  -e PORT=443 myimage

Uvicorn

Info

These settings are mostly used for local development.

WITH_RELOAD

  • Configure the Uvicorn auto-reload setting.
  • Default: "false" (don't auto-reload when files change)

  • Custom: "true" (watch files with watchgod and auto-reload when files change).

    Note

    Auto-reloading is useful for local development. Watchgod was added as an optional dependency in Uvicorn 0.11.4, and is included with inboard.

RELOAD_DIRS (new in inboard 0.7)

  • Directories and files to watch for changes with watchgod, formatted as comma-separated string.
  • Default: watch all directories under project root.

  • Custom:

    • "inboard" (one directory)
    • "inboard, tests" (two directories)
    • "inboard, tests, Dockerfile" (two directories and a file)

    Note

    On the command-line, this Uvicorn setting is configured by passing --reload-dir, and can be passed multiple times, with one directory each.

    However, when running Uvicorn programmatically, uvicorn.run accepts a list of strings (uvicorn.run(reload_dirs=["dir1", "dir2"])), so inboard will parse the environment variable, send the list to Uvicorn, and watchgod will watch each directory or file specified.

RELOAD_DELAY (new in inboard 0.11)

  • Floating point value specifying the time, in seconds, to wait before reloading files.
  • Default: not set (the value is set by uvicorn.config.Config)

  • Custom: "0.5"

    Note

    • uvicorn.run equivalent: reload_delay
    • Uvicorn CLI equivalent: --reload-delay

RELOAD_EXCLUDES (new in inboard 0.11)

  • Glob pattern indicating files to exclude when watching for changes with watchgod, formatted as comma-separated string.
  • Default: not set (the value is set by uvicorn.config.Config)

  • Custom: "*[Dd]ockerfile"

    Note

    • Parsed into a list of strings in the same manner as for RELOAD_DIRS.
    • uvicorn.run equivalent: reload_excludes
    • Uvicorn CLI equivalent: --reload-exclude

RELOAD_INCLUDES (new in inboard 0.11)

  • Glob pattern indicating files to include when watching for changes with watchgod, formatted as comma-separated string.
  • Default: not set (the value is set by uvicorn.config.Config)

  • Custom: "*.py, *.md"

    Note

    • Parsed into a list of strings in the same manner as for RELOAD_DIRS.
    • uvicorn.run equivalent: reload_includes
    • Uvicorn CLI equivalent: --reload-include

Logging

LOGGING_CONF

  • Python module containing a logging configuration dictionary object named LOGGING_CONFIG. Can be either a module path (inboard.logging_conf) or a file path (/app/inboard/logging_conf.py). The LOGGING_CONFIG dictionary will be loaded and passed to logging.config.dictConfig().
  • Default: "inboard.logging_conf" (the default module provided with inboard)
  • Custom: For a logging config module at /app/package/custom_logging.py, LOGGING_CONF="package.custom_logging" or LOGGING_CONF="/app/package/custom_logging.py".

LOG_COLORS

  • Whether or not to color log messages. Currently only supported for LOG_FORMAT="uvicorn".
  • Default:
  • Custom:
    • LOG_COLORS="true"
    • LOG_COLORS="false"

LOG_FORMAT

  • Python logging format.
  • Default:
    • "simple": Simply the log level and message.

  • Custom:

    • "verbose": The most informative format, with the first 80 characters providing metadata, and the remainder supplying the log message.
    • "gunicorn": Gunicorn's default format.
    • "uvicorn": Uvicorn's default format, similar to simple, with support for LOG_COLORS. Note that Uvicorn's access formatter is not supported here, because it frequently throws errors related to ASGI scope.

    Example log message in different formats

    # simple
INFO       Started server process [19012]

# verbose
2020-08-19 21:07:31 -0400      19012      uvicorn.error   main            INFO       Started server process [19012]

# gunicorn
[2020-08-19 21:07:31 -0400] [19012] [INFO] Started server process [19012]

# uvicorn (can also be colored)
INFO:     Started server process [19012]

LOG_LEVEL

  • Log level for Gunicorn or Uvicorn.
  • Default: "info"
  • Custom (organized from greatest to least amount of logging):
    • LOG_LEVEL="debug"
    • LOG_LEVEL="info"
    • LOG_LEVEL="warning"
    • LOG_LEVEL="error"
    • LOG_LEVEL="critical"

ACCESS_LOG

  • Access log file to which to write.
  • Default: "-" (stdout, print in Docker logs)
  • Custom:
    • ACCESS_LOG="./path/to/accesslogfile.txt"
    • ACCESS_LOG= (set to an empty value) to disable

ERROR_LOG

  • Error log file to which to write.
  • Default: "-" (stdout, print in Docker logs)
  • Custom:
    • ERROR_LOG="./path/to/errorlogfile.txt"
    • ERROR_LOG= (set to an empty value) to disable

See the logging reference for further info.

Authentication

BASIC_AUTH_USERNAME

  • Username for HTTP Basic auth.
  • Default: not set
  • Custom: BASIC_AUTH_USERNAME=test_user

BASIC_AUTH_PASSWORD

  • Password for HTTP Basic auth.
  • Default: not set
  • Custom: BASIC_AUTH_PASSWORD=r4ndom_bUt_memorable

See the authentication reference for further info.

Back to top