Playbook

Install Gunicorn

Gunicorn, and the Uvicorn worker for ASGI apps, in an application's own virtual environment.

Options

As they appear on the run form, with their defaults.

Application name

Text

Lowercase letters, digits and hyphens, such as api. Names the folder, account and service.

Default: Required

Python

One choice

On Ubuntu and Debian, both choices install the release's one Python 3.

Newest Python 3 in the distribution's repositories
The distribution's default python3

Default: Newest Python 3 in the distribution's repositories

Application interface

One choice

WSGI: Django, Flask
ASGI: FastAPI, Starlette, Django over ASGI

Default: WSGI: Django, Flask

When to use it

To run a Python web application in production. Gunicorn has to run from the environment that holds the application's dependencies, so this playbook creates that environment for one application. Run Install Python first with the same Python choice.

Choosing the options

Application name — lowercase letters, digits and hyphens, such as api or shop. It names the folder (/srv/api for api), and later the service account and systemd service that Configure Python App creates. Use the same name in both playbooks.

Python — the same choice you made in Install Python.

Application interface

WSGI: Django, Flask — traditional synchronous applications. Installs Gunicorn.
ASGI: FastAPI, Starlette, Django over ASGI — asynchronous applications. Installs Gunicorn with uvicorn-worker and uvicorn[standard], so Gunicorn manages Uvicorn workers.

What it does on the server

For an application named api:

Creates /srv/api and a virtual environment at /srv/api/venv with the chosen Python. The environment belongs to root, so the application's own account cannot change what it runs.
Upgrades pip inside the environment and installs Gunicorn, plus the Uvicorn worker for ASGI.
On SELinux systems, labels /srv/api/venv/bin so systemd is allowed to execute Gunicorn from it.
Checks that gunicorn runs, and for ASGI that the Uvicorn worker imports.

Existing packages are not upgraded. An environment already there that was made with a different Python is left alone.

After the run

Run Configure Python App with the same application name to create the service. Install your application's own requirements into the same environment, for api: /srv/api/venv/bin/pip install -r requirements.txt.

Common problems

"… is not installed. Run Install Python with the same Python choice first." — Install Python has not run with this Python choice. Run it, then this playbook again.

"… was made with Python …, not …. It was left alone" — The environment exists and uses another Python. Move it aside (for api, mv /srv/api/venv /srv/api/venv.old) or run this playbook with the Python it was made with.

"The Uvicorn worker does not import in …" — Installing the ASGI worker failed; the error is in the output. Often a compiler is missing for a dependency: run Install Python Tools with Install a compiler and build headers on, then this playbook again.