Boilerplate for FastAPI, Poetry, and Docker

The repo serves as a minimal reference on serving FastAPI application with Docker multi-stage builds using Poetry as environment management.

Go to Boilerplate for FastAPI, Pytest. Poetry, and Docker for a modified version with Pytest support included.

Requirements

• Poetry for Python package and environment management.
• FastAPI for Python RESTful API.
• Docker for containerization and deployment.

Project Structure

.
├── app                  # fastapi: source code 
│   ├── routers          
│   │   ├── __init__.py  
│   │   ├── items.py     # fastapi: example router "items"
│   │   └── users.py     # fastapi: example router "users"
│   ├── __init__.py
│   ├── config.py        # fastapi: app config
│   ├── dependencies.py  # fastapi: app dependencies
│   └── main.py          # fastapi: app entry point
├── Dockerfile           # docker: specified docker image
├── README.md
├── docker-compose.yml   # docker: specified docker compose
├── poetry.lock          # poetry: generated by poetry install
└── pyproject.toml       # poetry: specified package dependencies

Quickstart

Prerequisites

• Install Poetry following the official documentation.
• Install Docker following the official documentation.

Local Development

Create Poetry virtual environment by installing the project dependencies specified in pyproject.toml and poetry.lock.

poetry install

Run FastAPI development mode under Poetry virtual environment.

poetry run fastapi dev app/main.py

Alternatively, activate the Poetry nested shell and run FastAPI development mode. Exit the shell with exit.

poetry shell
fastapi dev app/main.py

By default the app services at http://127.0.0.1/, which is the localhost. The Swagger API documentation is available at http://127.0.0.1:8000/docs/.

Tip

The FastAPI local development mode has auto-reload enabled by default, so it will automatically reload the server when code changes are made. This is resource intensive and should only be used for development.

Dockerization

Build the Docker image.

docker image build -t fastapi-poetry-docker .

Run the Docker container.

docker run --rm -p 8000:80 fastapi-poetry-docker

Alternatively, build and run the Docker container with Docker compose.

docker compose up

The current configuration let the app services at http://0.0.0.0:8000/. The Swagger API documentation is available at http://0.0.0.0:8000/docs/.

Build from Scratch

Create Poetry Environment

Initialize pyproject.toml

Create a basic pyproject.toml file in the current directory.

cd [directory]
poetry init

The command will guide the process of creating the pyproject.toml config. Set python version as ^3.11. Provide the following packages as main dependencies.

• fastapi
• pydantic-settings

Manually add the following config to pyproject.toml to use Poetry only for dependency management but not for packaging.

[tool].poetry
package-mode = false

Optional: Add dependencies that are only needed for test and development, for example ipykernel.

poetry add ipykernel --group dev

Install Project Dependencies

Install the project dependencies specified in pyproject.toml and create Poetry virtual environment.

poetry install

Tip

List all the environments with the current project. The newly created environment should be shown and marked as Activated.

poetry env list

Get basic information about the currently activated environment.

poetry env info

List all the available packages installed in the environment.

poetry show