dizzbo/uvicorn-fastapi-docker

uvicorn-fastapi-docker

Docker image with https://www.uvicorn.org/ for high-performance https://fastapi.tiangolo.com/ web applications in https://www.python.org/ 3.6 and above. Targeted at running Fastapi on a kube cluster

Git repo: https://gitlab.com/dizzbo/devops/cicd_tools

Docker Hub image: https://hub.docker.com/r/dizzbo/uvicorn-fastapi-docker

Description

FastAPI has shown to be a Python web framework with one of the best performances, as measured by third-party benchmarks, thanks to being based on and powered by Starlette.

The achievable performance is on par with (and in many cases superior to) Go and Node.js frameworks.

Technical Details

Uvicorn

Uvicorn is a lightning-fast "ASGI" server.

It runs asynchronous Python web code in a single process.

FastAPI

FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.6+.

The key features are:

• Fast: Very high performance, on par with NodeJS and Go (thanks to Starlette and Pydantic).
• Fast to code: Increase the speed to develop features by about 200% to 300% *.
• Less bugs: Reduce about 40% of human (developer) induced errors. *
• Intuitive: Great editor support. Completion everywhere. Less time debugging.
• Easy: Designed to be easy to use and learn. Less time reading docs.
• Short: Minimize code duplication. Multiple features from each parameter declaration. Less bugs.
• Robust: Get production-ready code. With automatic interactive documentation.
• Standards-based: Based on (and fully compatible with) the open standards for APIs: https://github.com/OAI/OpenAPI-Specification (previously known as Swagger) and http://json-schema.org/.

* estimation based on tests on an internal development team, building production applications.

How to use

You don't need to clone the GitHub repo.

You can use this image as a base image for other images.

Assuming you have a file requirements.txt, you could have a Dockerfile like this:

Dockerfile
FROM dizzbo/uvicorn-fastapi-docker:python3.9

COPY ./requirements.txt /app/requirements.txt

RUN pip install --no-cache-dir --upgrade -r /app/requirements.txt

COPY ./app /app

It will expect a file at /app/app/main.py.

Or otherwise a file at /app/main.py.

And will expect it to contain a variable app with your FastAPI application.

Then you can build your image from the directory that has your Dockerfile, e.g:

bash
docker build -t myimage ./

Quick Start

Build your Image

• Go to your project directory.
• Create a Dockerfile with:

Dockerfile
FROM dizzbo/uvicorn-fastapi-docker:python3.9

COPY ./requirements.txt /app/requirements.txt

RUN pip install --no-cache-dir --upgrade -r /app/requirements.txt

COPY ./app /app

• Create an app directory and enter in it.
• Create a main.py file with:

Python
from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"Hello": "World"}


@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

• You should now have a directory structure like:

.
├── app
│   └── main.py
└── Dockerfile

• Go to the project directory (in where your Dockerfile is, containing your app directory).
• Build your FastAPI image:

bash
docker build -t myimage .

• Run a container based on your image:

bash
docker run -d --name mycontainer -p 80:80 myimage

Now you have an optimized FastAPI server in a Docker container. Auto-tuned for your current server (and number of CPU cores).

Check it

You should be able to check it in your Docker container's URL, for example: [] or [] (or equivalent, using your Docker host).

You will see something like:

JSON
{"item_id": 5, "q": "somequery"}

Interactive API docs

Now you can go to [] or [] (or equivalent, using your Docker host).

You will see the automatic interactive API documentation (provided by https://github.com/swagger-api/swagger-ui):

!https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png

Alternative API docs

And you can also go to [] or [] equivalent, using your Docker host).

You will see the alternative automatic documentation (provided by https://github.com/Rebilly/ReDoc):

!https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png

Dependencies and packages

You will probably also want to add any dependencies for your app and pin them to a specific version, probably including Uvicorn and FastAPI.

This way you can make sure your app always works as expected.

You could install packages with pip commands in your Dockerfile, using a requirements.txt, or even using https://python-poetry.org/.

And then you can upgrade those dependencies in a controlled way, running your tests, making sure that everything works, but without breaking your production application if some new version is not compatible.

Using Poetry

Here's a small example of one of the ways you could install your dependencies making sure you have a pinned version for each package.

Let's say you have a project managed with https://python-poetry.org/, so, you have your package dependencies in a file pyproject.toml. And possibly a file poetry.lock.

Then you could have a Dockerfile using Docker multi-stage building with:

Dockerfile
FROM python:3.9 as requirements-stage

WORKDIR /tmp

RUN pip install poetry

COPY ./pyproject.toml ./poetry.lock* /tmp/

RUN poetry export -f requirements.txt --output requirements.txt --without-hashes

FROM dizzbo/uvicorn-fastapi-docker:python3.9

COPY --from=requirements-stage /tmp/requirements.txt /app/requirements.txt

RUN pip install --no-cache-dir --upgrade -r /app/requirements.txt

COPY ./app /app

That will:

• Install poetry and configure it for running inside of the Docker container.
• Copy your application requirements.
  • Because it uses ./poetry.lock* (ending with a *), it won't crash if that file is not available yet.
• Install the dependencies.
• Then copy your app code.

It's important to copy the app code after installing the dependencies, that way you can take advantage of Docker's cache. That way it won't have to install everything from scratch every time you update your application files, only when you add new dependencies.

This also applies for any other way you use to install your dependencies. If you use a requirements.txt, copy it alone and install all the dependencies on the top of the Dockerfile, and add your app code after it.

Advanced usage

Environment variables

These are the environment variables that you can set in the container to configure it and their default values:

MODULE_NAME

The Python "module" (file) to be imported by Uvicorn, this module would contain the actual application in a variable.

By default:

• app.main if there's a file /app/app/main.py or
• main if there's a file /app/main.py

For example, if your main file was at /app/custom_app/custom_main.py, you could set it like:

bash
docker run -d -p 80:80 -e MODULE_NAME="custom_app.custom_main" myimage

VARIABLE_NAME

The variable inside of the Python module that contains the FastAPI application.

By default:

• app

For example, if your main Python file has something like:

Python
from fastapi import FastAPI

api = FastAPI()


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

In this case api would be the variable with the FastAPI application. You could set it like:

bash
docker run -d -p 80:80 -e VARIABLE_NAME="api" myimage

APP_MODULE

The string with the Python module and the variable name passed to Uvicorn.

By default, set based on the variables MODULE_NAME and VARIABLE_NAME:

• app.main:app or
• main:app

You can set it like:

bash
docker run -d -p 80:80 -e APP_MODULE="custom_app.custom_main:api" myimage

HOST

The "host" used by Uvicorn, the IP where Uvicorn will listen for requests.

It is the host inside of the container.

So, for example, if you set this variable to 127.0.0.1, it will only be available inside the container, not in the host running it.

It's is provided for completeness, but you probably shouldn't change it.

By default:

• 0.0.0.0

PORT

The port the container should listen on.

If you are running your container in a restrictive environment that forces you to use some specific port (like 8080) you can set it with this variable.

By default:

• 80

You can set it like:

bash
docker run -d -p 80:8080 -e PORT="8080" myimage

LOG_LEVEL

The log level for Uvicorn.

One of:

• debug
• info
• warning
• error
• critical

By default, set to info.

If you need to squeeze more performance sacrificing logging, set it to warning, for example:

You can set it like:

bash
docker run -d -p 80:8080 -e LOG_LEVEL="warning" myimage

PRE_START_PATH

The path where to find the pre-start script.

By default, set to /app/prestart.sh.

You can set it like:

bash
docker run -d -p 80:8080 -e PRE_START_PATH="/custom/script.sh" myimage

Custom /app/prestart.sh

If you need to run anything before starting the app, you can add a file prestart.sh to the directory /app. The image will automatically detect and run it before starting everything.

For example, if you want to add Alembic SQL migrations (with SQLALchemy), you could create a ./app/prestart.sh file in your code directory (that will be copied by your Dockerfile) with:

bash
#! /usr/bin/env bash

# Let the DB start
sleep 10;
# Run migrations
alembic upgrade head

and it would wait 10 seconds to give the database some time to start and then run that alembic command.

If you need to run a Python script before starting the app, you could make the /app/prestart.sh file run your Python script, with something like:

bash
#! /usr/bin/env bash

# Run custom Python script before starting
python /app/my_custom_prestart_script.py

You can customize the location of the prestart script with the environment variable PRE_START_PATH described above.

Development live reload

The default program that is run is at /start.sh. It does everything described above.

There's also a version for development with live auto-reload at:

bash
/start-reload.sh

Details

For development, it's useful to be able to mount the contents of the application code inside of the container as a Docker "host volume", to be able to change the code and test it live, without having to build the image every time.

In that case, it's also useful to run the server with live auto-reload, so that it re-starts automatically at every code change.

It is ideal for development.

Usage

For example, instead of running:

bash
docker run -d -p 80:80 myimage

You could run:

bash
docker run -d -p 80:80 -v $(pwd):/app myimage /start-reload.sh

• -v $(pwd):/app: means that the directory $(pwd) should be mounted as a volume inside of the container at /app.
  • $(pwd): runs pwd ("print working directory") and puts it as part of the string.
• /start-reload.sh: adding something (like /start-reload.sh) at the end of the command, replaces the default "command" with this one. In this case, it replaces the default (/start.sh) with the development alternative /start-reload.sh.

License

This project is licensed under the terms of the MIT license.