Deployment

A development setup has one process: pserve development.ini --reload starts Waitress, which serves everything, including the debug toolbar and the static files. A production setup separates the jobs. A reverse proxy faces the internet, terminates TLS, buffers slow clients and serves the static files from disk; a WSGI server runs several worker processes that import the application once and answer the dynamic requests; configuration comes from a hardened production.ini plus environment variables; and every worker owns its own pool of database connections.

The table lists what changes between the two setups and where this page covers it.

Deployment does not change how an application is written, but it adds three habits that the example below follows. The application is created by an entry point that every server can load by name (main(global_config, **settings), the PasteDeploy convention from the cookiecutter project). Its secret comes from the environment and the process refuses to start without it, so a missing secret is found at deployment time and not at the first login. And its cookies are configured for HTTPS: SignedCookieSessionFactory takes secure, httponly and samesite arguments.

The first example writes a small project into a temporary directory: the package, a static file, and a production.ini. A project generated by the cookiecutter has the same shape; the only difference is the first line of [app:main], which is use = egg:bookshelf_shelves there (an entry point of an installed package) and is use = call:bookshelf_shelves:main here because the temporary directory is not installed. Everything else on this page loads that file. The secret is generated with secrets.token_hex() and passed through an environment variable, which stands for what systemd, Docker or Kubernetes would provide.

Source: Pyramid: Creating a Pyramid Project

Source: Pyramid: SignedCookieSessionFactory

Three details of the file deserve a comment. The server section interpolates two variables, %(http_port)s and %(proxy_ip)s, which pserve production.ini http_port=8000 proxy_ip=127.0.0.1 supplies from the command line; the examples below use this to pick a free port (the settings page describes this PasteDeploy feature). The file deliberately defines no defaults for them: PasteDeploy does not let a command-line variable overwrite a value that [DEFAULT] already has, and a missing variable fails when the server section is read, which is the behaviour a deployment wants. Gunicorn and uWSGI never read that section, so they are unaffected. The logging sections at the end are the ones that pserve and gunicorn --paste hand to logging.config.fileConfig; the logging page explains them. And the secret appears nowhere in the file.

The next example defines the helpers that the rest of the page uses: a free port, a server starter that waits for /healthz, a JSON fetcher and a function that sends a signal and returns what the server printed.

Source: Python: subprocess

The production.ini of the cookiecutter project is already close to what a server needs; the work is to keep it that way. The checklist below is what to review in the file, and an environment audit follows, because environment variables silently win over the file.

Every pyramid.* setting can also be set through a PYRAMID_* environment variable (PYRAMID_RELOAD_TEMPLATES=1), and the environment value wins over the .ini file, as the settings page explains. The unprefixed names (reload_templates) are accepted too, and the audit checks them. A shell that a developer used to debug a problem, a stray line in a systemd environment file or a Compose environment: block is enough to re-enable a switch that the file keeps off. A small audit run at start-up, or in the deployment pipeline against the real environment, turns that into a failed deployment rather than a surprise. The function below reads the settings through the same get_appsettings the application uses and checks both sources. The second call hands it a development-style configuration to show a failing audit; the real file passes.

Source: Pyramid: Environment Variables and .ini File Settings

pyramid.paster.get_appsettings is the call to use in a deployment script: it applies the plaster loader (the PasteDeploy loader for .ini files) without constructing the application. The same file therefore serves the application, the audit, the p* scripts and the migrations.

Waitress is the server named in every generated .ini file (use = egg:waitress#main). It is a pure-Python, multi-threaded WSGI server with no dependencies, it runs on Windows as well as Unix, and its documentation describes it as production quality. It has one process and a pool of threads (threads, default 4), so it uses one core for Python code at a time; scale it by running several processes behind the proxy, or choose Gunicorn if you want the server to manage the processes for you. It does not terminate TLS, which is the first reason it always sits behind a proxy in production.

Waitress takes the same arguments in three places: as keyword arguments of waitress.serve(), as the options of the waitress-serve command, and as keys of the [server:main] section (the table lists the ones that matter for a deployment, with the defaults from the official page).

Source: Waitress: Arguments to waitress.serve

Gunicorn is a pre-fork server: a master process starts workers, each worker imports the application and handles requests, and the master restarts workers that die or hang. It has been the usual production server for Pyramid for years because it reads the same .ini file as pserve. Pyramid uses the PasteDeploy loader for that, so --paste is all the integration needed.

Pre-fork servers (Gunicorn with preload_app, uWSGI by default) import the application once and fork the workers, so anything created at import time is shared by every worker: open sockets, file descriptors, random-number generator state and connection pools. The Community Cookbook has a short page on this ("Forked and Threaded Servers") and its main example is still right: an SQLAlchemy Engine that has opened a connection before the fork hands the same socket to every worker, and two workers speaking on one database connection corrupt each other. A Pyramid application that connects only inside requests (the usual request.dbsession pattern of the SQLAlchemy page) is safe, because pools connect lazily; one that connects while the application is created, to check the schema or to warm a cache, must reset the pool in every child. SQLAlchemy’s documentation gives the recipe: engine.dispose(close=False) in the child, which discards the inherited connections without closing the sockets that the parent still uses.

The example builds a small application with an engine that connects during import, runs it under Gunicorn with --preload, and has the hook report the pool before and after.

Source: SQLAlchemy: Using Connection Pools with Multiprocessing or os.fork()

Each worker found one checked-in connection inherited from the master and dropped it. uWSGI has the same hook as uwsgidecorators.postfork, and the Waitress case is different in kind: it does not fork, but its threads share the engine, which is what the pool is designed for. The Cookbook page also mentions seeding the PyCrypto random generator after a fork; that library is unmaintained, and the standard library’s secrets and os.urandom do not need it.

mod_wsgi embeds Python in Apache httpd. The official Pyramid tutorial is the reference, and it is short: a project created from the cookiecutter, a pyramid.wsgi script, and a handful of Apache directives. The script is the part that is Pyramid’s:

Source: Pyramid: Running a Pyramid Application under mod_wsgi

The script was executed the way mod_wsgi does it, and the application it exposes answered. The assignment to the name application is mandatory: mod_wsgi looks for it by name. setup_logging is needed because, unlike pserve, mod_wsgi never reads the logging sections of the .ini file. The Apache side is the configuration of the official tutorial (not run here; the python-path must name the virtual environment that holds the application):

Source: Pyramid: Running a Pyramid Application under mod_wsgi

The three non-obvious lines are the ones the tutorial explains. WSGIApplicationGroup %{GLOBAL} runs the application in the main Python interpreter instead of a sub-interpreter, because sub-interpreters do not get along with C extensions; WSGIPassAuthorization On passes the Authorization header through, which Apache otherwise withholds from WSGI (security policies that read it, such as token authentication, need it); and WSGIDaemonProcess with WSGIProcessGroup runs the application in separate daemon processes under their own user, not inside Apache’s. The WSGIScriptAlias /shelves ... line also mounts the application at a prefix: mod_wsgi sets SCRIPT_NAME for you (see virtual hosting). The interpreter that mod_wsgi was built against must be the one that created the virtual environment. mod_wsgi-express (pip install mod_wsgi) starts a private Apache from the command line and is the easier way to try it; it needs a Python library that the operating system allows Apache to load, which is the failure that stopped it on the macOS machine used for this page. The Flask page covers mod_wsgi-express on Linux in more detail.

uWSGI also understands PasteDeploy: the --paste option takes a config: URI of the .ini file, and the Cookbook has three recipes around it. pyuwsgi is the wheel-installable build of uWSGI; it provides the uwsgi command.

Source: Pyramid Community Cookbook: uWSGI

Source: uWSGI: Configuring uWSGI

--need-app makes uWSGI exit when the application cannot be loaded, instead of running a server that answers every request with an error; --die-on-term makes SIGTERM stop the process, because uWSGI by default interprets it as a reload request, which breaks supervisors and container runtimes (uWSGI documents that SIGTERM means "brutally reload the stack" until 2.1). %d in the .ini form is the directory of the configuration file. Run uWSGI behind a proxy that speaks its protocol (uwsgi_pass in nginx, with --socket) or plain HTTP (--http-socket, as above); --http starts uWSGI’s own router and is not for the internet.

The proxy does what the Python server should not: TLS, slow clients, limits, static files, compression and the Host/X-Forwarded-* headers. The configuration below is the one used with the Docker example later in the page. It was validated with nginx -t in an nginx 1.29 container; the proxy-to-Pyramid path was checked with the servers and header combinations of the earlier examples.

Source: nginx: ngx_http_proxy_module

Source: Gunicorn: Deploy

Line by line: Host $host passes the public host name, which Pyramid uses for every absolute URL (route_url, redirects, resource_url); the Waitress documentation asks for exactly this header. X-Forwarded-Proto $scheme tells the application that the client used HTTPS, so that links and secure cookies come out right. keepalive together with proxy_http_version 1.1 and an empty Connection header reuses upstream connections. location /static/ serves the files without Python; the alias directory must hold the same files as the package’s static directory (mount or copy them into the proxy’s file system at deployment time), and the URL prefix must match the path of the static view. The generated project’s static view is /static, which is why no rewrite is needed. With a sync Gunicorn worker the proxy is not optional: the worker handles one request at a time, so a client that sends its request slowly would occupy it, and nginx buffers the request until it is complete.

Sometimes the application does not live at the root of the site: https://example.org/bookshelf/ is the application, https://example.org/ is something else. The WSGI answer is SCRIPT_NAME, the part of the path that the server has consumed before the application starts; Pyramid’s route_url, route_path, static_url and resource_url prepend it, and routing matches against PATH_INFO, the rest. The official Virtual Hosting chapter describes the two situations, and there are several ways to set SCRIPT_NAME, each with a different trust model.

Source: Pyramid: Virtual Hosting

Source: PasteDeploy: paste.deploy.config

Without any of them, an application served under a prefix generates links without it: the browser then asks the proxy for /home instead of /bookshelf/home, and gets the wrong site. The example mounts one small application, a resource tree with a URL-dispatch route and a view for shelves, in the four first ways, and prints what the application sees.

Source: Pyramid: Virtual Hosting

Read the outputs against the table. rutter mounts the application and builds prefixed URLs from the path, and it does not look at X-Forwarded-Host: the generated URL keeps the Host it received, which is the official chapter’s warning. PrefixMiddleware does translate the forwarded headers, which is convenient behind a proxy and wrong for a server that clients can reach directly, because anybody can then choose the scheme and host of the URLs the application generates; use it only when the proxy is the sole route to the server, or prefer Waitress’s trusted_proxy. Waitress’s url_prefix is the simplest and the least flexible. X-Vhm-Root is a traversal feature: the resource URLs of the virtual root come out without the physical path (http://localhost/dune/ for a resource that is at /ada/dune in the tree), and the header is only honoured, as written in the chapter, by traversal; a URL-dispatch route is unaffected. The header comes from the proxy, so the proxy must overwrite whatever the client sent, as with X-Forwarded-For. In every case the proxy rewrites or strips the prefix as the mechanism requires (rutter and WSGIScriptAlias expect the prefix to arrive, Waitress’s url_prefix also accepts requests without it).

Nothing in the topology restarts itself. A supervisor starts the services at boot, restarts them when they crash, stops them with the signal the server expects, and collects their logs. On a Linux host that is systemd. In a container the runtime plays that role and the server runs in the foreground (see Docker and Kubernetes). A unit for the Gunicorn setup of this page runs as an unprivileged user, reads the secrets from an environment file owned by root with mode 0600, stops with SIGTERM (the graceful signal measured above) and reloads with SIGHUP, which makes the master start new workers and retire the old ones gracefully. It was not run: the verification host is not Linux.

Source: systemd.service(5)

TimeoutStopSec is a little longer than graceful_timeout, so that systemd does not kill the workers before Gunicorn does. pserve is not a supervisor: the Cookbook’s "nginx + pserve + supervisord" recipe combines it with Supervisor, which still works, but a unit file gives the same with less. A --reload start never belongs in a unit, and the process must stay in the foreground.

A container image of a Pyramid application is a Python image, the installed package, production.ini and Gunicorn as the entry point; pserve and Waitress are fine for a single replica but do not stop gracefully on SIGTERM. The generic material (layers, multi-stage builds, non-root users, image scanning) is covered by the Dockerfile fundamentals, multi-stage builds and image best practices pages. The Pyramid-specific points are few: install the package into the image and not from the source tree, so that the entry point egg:bookshelf_shelves resolves; install Gunicorn there and not the debug toolbar; keep the secrets out of the image; and point --worker-tmp-dir at memory.

The Dockerfile below builds wheels in a first stage and installs them into a slim image that runs as a numeric non-root user (Kubernetes' runAsNonRoot check needs a numeric id). It was built and run with Docker 29.8.2 and python:3.13-slim, on the project of this page packaged with a pyproject.toml that has a paste.app_factory entry point, with a read-only root file system and /dev/shm as a memory file system; behind the nginx configuration above the container answered /healthz, /whoami reported the address that nginx had written into X-Forwarded-For and not the forged one, and docker stop ended it in a third of a second, because Gunicorn handles SIGTERM gracefully.

Source: Docker: Multi-stage builds

PYTHONUNBUFFERED=1 makes the logs appear immediately. The bind is 0.0.0.0 because inside a container the proxy reaches the process over the container network; what keeps it private is the network, not the address. Gunicorn’s forwarded_allow_ips default (loopback) then does not match the proxy’s address, so X-Forwarded-Proto is ignored; set FORWARDED_ALLOW_IPS to the proxy’s network (a CIDR such as 10.0.0.0/8 is accepted) in the environment of the container. In Kubernetes the manifest provides what the image does not have: replicas, the secret from a Secret, and probes on the /healthz view, which does no database work and therefore only reports that the process answers.

Source: Kubernetes: Configure Liveness, Readiness and Startup Probes

The terminationGracePeriodSeconds is longer than Gunicorn’s graceful_timeout (30), so that the kubelet’s SIGKILL arrives after the workers have finished. The Secret, the Ingress that replaces nginx, rolling updates and probes have their own pages on this site: Secrets, Health probes and lifecycle, ReplicaSets and Deployments, Services and Ingress. Migrations (see SQLAlchemy, Transactions & Migrations) are one more command, alembic upgrade head, run once per release by a Job or an init step, never by every replica at start-up.

Pyramid is a WSGI framework and there is no ASGI-native Pyramid. The Cookbook’s ASGI page shows the supported route: wrap the WSGI application with asgiref.wsgi.WsgiToAsgi, and run the result with an ASGI server such as Uvicorn or Hypercorn. The wrapper runs each request in a thread pool, so the application stays synchronous and nothing becomes faster; the reasons to do it are a platform that only offers ASGI servers, or sharing a process with ASGI components. The page itself warns that not every WSGI feature survives the conversion (file handles of incoming POST bodies are named), and that its WebSocket extension is one possible design, not a feature of Pyramid. The Tornado page on WSGI interoperability covers the opposite direction, serving a WSGI application from inside an asynchronous server, and the FastAPI page on WSGI middleware the same idea with a different host.

Source: Pyramid Community Cookbook: ASGI

Source: ASGI: HTTP and WebSocket specification

The application answered through Uvicorn. Uvicorn reports that the lifespan protocol is unsupported, which is harmless for a wrapped WSGI application (no start-up or shutdown events exist to receive). The proxy headers follow Uvicorn’s own rules (--proxy-headers and --forwarded-allow-ips), not Pyramid’s or Waitress’s, so a deployment of this kind needs the same attention to who may set X-Forwarded-For as above.

The Pyramid Community Cookbook has a Deployment section whose pages were last built on 2022-04-22 (Sphinx 1.8.6). Some are current because the facts they describe have not changed; some describe platforms that no longer exist. The list is a reading guide, not a verdict on every line of each page.

Source: Pyramid Community Cookbook: Deployment

The official manual’s own deployment content is the mod_wsgi tutorial, the virtual hosting chapter, the production.ini generated by the cookiecutter and the Waitress documentation; the cookiecutter-generated project page of the manual (narr/project) is partly stale, as the cookiecutter page of this section notes.

The sizing rules are the generic ones of the Flask deployment page, and nothing in Pyramid changes them, but the Pyramid-specific parts are worth stating.