fastapi-uv-starter

A starter project using Python, FastAPI and uv.

• fastapi-uv-starter
  • Description
  • Getting Started
  • Development
  • Containerisation
    • 1. Build image and tag it as fastapi-uv-starter
    • 2. Run a container of the previously tagged image (fastapi-uv-starter)
    • 3. Check running containers
    • 4. Hit sample endpoint

Description

A project starter for personal usage containing the following:

• Python 3.15.*
• FastAPI web framework
• Structured logging using structlog
• Dependency management using uv
• Toolchain management using mise
• Containerisation using a Dockerfile
• Testing with pytest and optionally with coverage with pytest-cov
• Linting/formatting using Ruff
• Type checking using ty
• .gitignore

Getting Started

mise manages the pinned toolchain (Python 3.15.2, uv 0.13.7).

macOS / Linux

curl https://mise.run | sh

Windows

winget install jdx.mise

Activate mise in your shell so the pinned versions take precedence over any system installs (Homebrew, etc.). In ~/.zshrc:

eval "$(mise activate zsh)"

Then, in the repo:

mise trust        # one-time, confirms you trust this repo's mise.toml
mise install      # downloads and pins Python and uv
mise run install  # installs dependencies into .venv

Development

Command	Description
mise run install	Install dependencies into .venv
mise run dev	FastAPI dev server on 127.0.0.1:8000
mise run serve	Production server on 0.0.0.0:8000
mise run test	Run tests with coverage
mise run fmt	Format code via ruff format
mise run lint	Lint code via ruff check
mise run typecheck	Type check via ty check
mise run vuln	Audit deps for known vulnerabilities
mise run deps	Update and sync dependencies

Containerisation

The following podman commands are direct replacements of the Docker CLI. You can see that their syntax is identical:

1. Build image and tag it as fastapi-uv-starter

podman image build -t fastapi-uv-starter .

2. Run a container of the previously tagged image (fastapi-uv-starter)

Run our FastAPI application and map our local port 8000 to 8000 on the running container:

podman container run -d --name fastapi-uv-starter -p 8000:8000 --network bridge fastapi-uv-starter

3. Check running containers

podman ps

CONTAINER ID  IMAGE                            COMMAND               CREATED         STATUS             PORTS                 NAMES
78586e5b4683  localhost/fastapi-uv-starter:latest  fastapi run app/...     13 minutes ago  Up 5 minutes ago  0.0.0.0:8000->8000/tcp  nifty_roentgen

4. Hit sample endpoint

Our FastAPI server now runs on port 8000 on our local machine. We can test it with:

curl -i http://localhost:8000/healthcheck

Output:

HTTP/1.1 200 OK
server: uvicorn
content-length: 0