uvicorn-gunicorn-poetry - GitLite

KO | EN

gitlite — search

#python #go #golang #android #rust #linux #awesome #cli #awesome-list #security #pytorch #mcp #openai #open-source

uvicorn-gunicorn-poetry

(★ 128)

Docker image with Gunicorn using Uvicorn workers for running Python web applications. Uses Poetry for managing dependencies and setting up a virtual environment. Supports AMD64 and ARM64 CPU architectures.

File Explorer

Download Latest Version (.zip)

- - pipeline.yml
- __init__.py
- constants.py
- Dockerfile
- gunicorn_configuration.py
- publish.py
- utils.py
- - .dockerignore
  - .gitignore
  - Dockerfile
  - poetry.lock
  - pyproject.toml
  - README.md
- - .dockerignore
  - .gitignore
  - Dockerfile
  - poetry.lock
  - pyproject.toml
  - README.md
- - __init__.py
  - conftest.py
  - test_build_version.py
  - test_default_configuration.py
- - __init__.py
  - conftest.py
  - test_cli.py
  - test_cli_and_env.py
  - test_env.py
- __init__.py
- conftest.py
- constants.py
- utils.py
.env-example
.gitignore
.pre-commit-config.yaml
LICENSE
poetry.lock
pyproject.toml
README.md

# Installation Guide

1. Get the code

git clone https://github.com/max-pfeiffer/uvicorn-gunicorn-poetry

Downloads the entire project code from GitHub to your computer.

cd uvicorn-gunicorn-poetry

Moves into the project folder you just downloaded.

2. Docker

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Docker Desktop Needed to build and run containers. Install it and keep it running in the background.

docker build -f build/Dockerfile -t uvicorn-gunicorn-poetry .

Builds a runnable image based on the Dockerfile.

docker run -p 8080:80 uvicorn-gunicorn-poetry

Runs the built image as an actual container.

✅ Run docker compose ps to check the containers are Up. If the README mentions a port, open http://localhost:PORT in your browser.

3. Python

Easy

Prerequisites

Git Needed to download the project code from GitHub.
Python 3 On Windows, be sure to check 'Add Python to PATH' during installation.

├── poetry.lock

Type this command into your terminal and run it.

✅ If it runs without errors and prints output in the terminal, it worked.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![codecov](https://codecov.io/gh/max-pfeiffer/uvicorn-gunicorn-poetry/graph/badge.svg?token=ZRUKVNP3I5)](https://codecov.io/gh/max-pfeiffer/uvicorn-gunicorn-poetry)
![pipeline workflow](https://github.com/max-pfeiffer/uvicorn-gunicorn-poetry/actions/workflows/pipeline.yml/badge.svg)
![Docker Image Size (latest semver)](https://img.shields.io/docker/image-size/pfeiffermax/uvicorn-gunicorn-poetry?sort=semver)
![Docker Pulls](https://img.shields.io/docker/pulls/pfeiffermax/uvicorn-gunicorn-poetry)
# uvicorn-gunicorn-poetry - Docker image for FastAPI
This Docker image provides a platform to run Python applications with [Gunicorn](https://gunicorn.org) as process manager and
[Uvicorn](https://www.uvicorn.org/) workers.
It provides [Poetry](https://python-poetry.org/) for managing dependencies and setting up a virtual environment in the container.

This image aims to follow the best practices for a production grade container image for hosting Python web applications based
on micro frameworks like [FastAPI](https://fastapi.tiangolo.com/).
Therefore, source and documentation contain a lot of references to documentation of dependencies used in this project, so users
of this image can follow up on that.

If you would like to run your Python application with Uvicorn on [Kubernetes](https://kubernetes.io/), please check out my other project which does not use
Gunicorn as process manager: https://github.com/max-pfeiffer/uvicorn-poetry

Any feedback is highly appreciated and will be considered.

**Docker Hub:** [pfeiffermax/uvicorn-gunicorn-poetry](https://hub.docker.com/r/pfeiffermax/uvicorn-gunicorn-poetry)

**GitHub Repository:** [https://github.com/max-pfeiffer/uvicorn-gunicorn-poetry](https://github.com/max-pfeiffer/uvicorn-gunicorn-poetry)

## Docker Image Features
1. Poetry v1.8.2 is available as Python package dependency management tool
2. A virtual environment for the application and application server
3. The application is run with [Gunicorn](https://gunicorn.org/) and Uvicorn workers
4. Python versions:
    1. 3.10
    2. 3.11
    3. 3.12
5. Operating system variants:
    1. [Debian Bookworm v12.1](https://www.debian.org/releases/bookworm/)
    2. [Debian Bookworm slim v12.1](https://www.debian.org/releases/bookworm/)
6. Supported CPU architectures:    
   1. linux/amd64
   2. linux/arm64/v8

## Usage
It just provides a platform that you can use to build upon your own multistage builds. So it consequently does not contain an
application itself.

Please check out the [example application for multistage builds](https://github.com/max-pfeiffer/uvicorn-gunicorn-poetry/tree/master/examples/fast_api_multistage_build)
on how to use that image and build containers efficiently.

There is also another [sample app demonstrating a very simple single stage build](https://github.com/max-pfeiffer/uvicorn-gunicorn-poetry/tree/main/examples/fast_api_singlestage_build).

Please be aware that your application needs an application layout without src folder which is proposed in
[fastapi-realworld-example-app](https://github.com/nsidnev/fastapi-realworld-example-app).
The application and test structure needs to be like that:
```bash
├── Dockerfile
├── app
│   ├── __init__.py
│   └── main.py
├── poetry.lock
├── pyproject.toml
└── tests
    ├── __init__.py
    ├── conftest.py
    └── test_api
        ├── __init__.py
        ├── test_items.py
        └── test_root.py
```
Please be aware that you need to provide a pyproject.toml file to specify your Python package dependencies for Poetry and configure
dependencies like Pytest. Poetry dependencies must at least contain the following to work:
* python = "^3.10"
* gunicorn = "22.0.0"
* uvicorn = "0.29.0"

If your application uses FastAPI framework this needs to be added as well:
* fastapi = "0.110.2"

**IMPORTANT:** make sure you have a [.dockerignore file](https://github.com/max-pfeiffer/uvicorn-gunicorn-poetry/blob/master/examples/fast_api_multistage_build/.dockerignore)
in your application root which excludes your local virtual environment in .venv! Otherwise, you will have an issue activating that virtual
environment when running the container.

## Configuration
Configuration is done through the following environment variables during docker build.
For all the following configuration options please see always the
[official Gunicorn documentation](https://docs.gunicorn.org/en/stable/settings.html)
if you would like to do a deep dive. Following environment variables are supported:

### [Logging](https://docs.gunicorn.org/en/stable/settings.html#logging)
`LOG_LEVEL` : The granularity of Error log outputs. Valid level names are:
* debug
* info
* warning
* error
* critical
 
**default:** `info`

`ACCESS_LOG` : The Access log file to write to.

**default:** `-`

`ERROR_LOG` : The Error log file to write to.

**default:** `-`

### [Worker processes](https://docs.gunicorn.org/en/stable/settings.html#worker-processes)
`WORKERS` : The number of worker processes for handling requests. By default, this is set to one
worker as this image is meant to be used on a production grade Kubernetes environment. There you
have usually monitoring data exported to Prometheus which will not work properly with multiple workers.

**default:** `1`

`TIMEOUT` : Workers silent for more than this many seconds are killed and restarted.

**default:** `30`

`GRACEFUL_TIMEOUT` : Timeout for graceful workers restart.

**default:** `30`

`KEEP_ALIVE` : The number of seconds to wait for requests on a Keep-Alive connection.

**default:** `2`

### [Server mechanics](https://docs.gunicorn.org/en/stable/settings.html?highlight=worker_tmp_dir#worker-tmp-dir)
`WORKER_TMP_DIR` : A directory to use for the worker heartbeat temporary file.
By default, this is set to /dev/shm to speed up the startup of workers by using a in memory file system

**default:** `/dev/shm`

### [Server socket](https://docs.gunicorn.org/en/stable/settings.html?highlight=bind#bind)
`BIND` : The socket to bind.

**default:** `0.0.0.0:8000`