FastAPI Template

This is a template repository for FastAPI web service projects.

✨ Features

• FastAPI
• REST API
• Web service
• Microservice
• Configuration
• Tests
• Build
• Scripts
• Examples
• Documentation
• CI/CD
• Docker and docker compose

---

🐤 Getting Started

1. 🚧 Prerequisites

[RECOMMENDED] For docker runtime:

• Install docker and docker compose
  • Docker image: bybatkhuu/rest-fastapi-template

For standalone runtime:

• Install Python (>= v3.10) and pip (>= 23):
  • [RECOMMENDED] Miniconda (v3)
  • [arm64/aarch64] Miniforge (v3)
  • [Python virtual environment] venv

[OPTIONAL] For DEVELOPMENT environment:

• Install git
• Setup an SSH key

2. 📥 Download or clone the repository

2.1. Prepare projects directory (if not exists):

# Create projects directory:
mkdir -pv ~/workspaces/projects

# Enter into projects directory:
cd ~/workspaces/projects

2.2. Follow one of the below options [A], [B] or [C]:

OPTION A. Clone the repository:

git clone https://github.com/bybatkhuu/rest-fastapi-template.git && \
    cd rest-fastapi-template

OPTION B. Clone the repository (for DEVELOPMENT: git + ssh key):

git clone git@github.com:bybatkhuu/rest-fastapi-template.git && \
    cd rest-fastapi-template

OPTION C. Download source code:

1. Download archived zip or tar.gz file from releases.
2. Extract it into the projects directory.
3. Enter into the project directory.

3. 📦 Install dependencies

[TIP] Skip this step, if you're going to use docker runtime

pip install -r ./requirements.txt

# For DEVELOPMENT:
pip install -r ./requirements/requirements.dev.txt
# Install pre-commit hooks:
pre-commit install

4. 🌎 Configure environment variables

[NOTE] Please, check environment variables section for more details.

# Copy '.env.example' file to '.env' file:
cp -v ./.env.example ./.env
# Edit environment variables to fit in your environment:
nano ./.env

5. 🏁 Start the server

[NOTE] Follow the one of below instructions based on your environment [A, B, C, D, E]:

Docker runtime

OPTION A. [RECOMMENDED] Run with docker compose:

## 1. Configure 'compose.override.yml' file.
# Copy 'compose.override.[ENV].yml' file to 'compose.override.yml' file:
cp -v ./templates/compose/compose.override.[ENV].yml ./compose.override.yml
# For example, DEVELOPMENT environment:
cp -v ./templates/compose/compose.override.dev.yml ./compose.override.yml
# For example, STATGING or PRODUCTION environment:
cp -v ./templates/compose/compose.override.prod.yml ./compose.override.yml
# Edit 'compose.override.yml' file to fit in your environment:
nano ./compose.override.yml

## 2. Check docker compose configuration is valid:
./compose.sh validate
# Or:
docker compose config

## 3. Start docker compose:
./compose.sh start -l
# Or:
docker compose up -d --remove-orphans --force-recreate && \
    docker compose logs -f -n 100

Standalone runtime (PM2)

OPTION B. Run with PM2:

[IMPORTANT] Before running, need to install PM2:

## 1. Configure PM2 configuration file.
# Copy example PM2 configuration file:
cp -v ./pm2-process.json.example ./pm2-process.json
# Edit PM2 configuration file to fit in your environment:
nano ./pm2-process.json

## 2. Start PM2 process:
pm2 start ./pm2-process.json && \
    pm2 logs --lines 50 ft

Standalone runtime (Python)

OPTION C. Run server as python module:

python -u -m src.api

OPTION D. Run with uvicorn cli:

uvicorn src.api.main:app --host=[BIND_HOST] --port=[PORT] --no-access-log --no-server-header --proxy-headers --forwarded-allow-ips="*"
# For example:
uvicorn src.api.main:app --host="0.0.0.0" --port=8000 --no-access-log --no-server-header --proxy-headers --forwarded-allow-ips="*"

# For DEVELOPMENT:
uvicorn src.api.main:app --host="0.0.0.0" --port=8000 --no-access-log --no-server-header --proxy-headers --forwarded-allow-ips="*" --reload --reload-dir=./src

OPTION E. Run with fastapi cli:

fastapi run src/api/main.py --host=[BIND_HOST] --port=[PORT] --forwarded-allow-ips="*"
# For example:
fastapi run src/api/main.py --port=8000 --forwarded-allow-ips="*"

# For DEVELOPMENT:
fastapi dev src/api/main.py --host="0.0.0.0" --port=8000 --forwarded-allow-ips="*"

6. ✅ Check server is running

Check with CLI (curl):

# Send a ping request with 'curl' to REST API server and parse JSON response with 'jq':
curl -s http://localhost:8000/api/v1/ping | jq

Check with web browser:

• Health check: http://localhost:8000/api/v1/health
• Swagger: http://localhost:8000/docs
• Redoc: http://localhost:8000/redoc
• OpenAPI JSON: http://localhost:8000/openapi.json

7. 🛑 Stop the server

Docker runtime:

# Stop docker compose:
./compose.sh stop
# Or:
docker compose down --remove-orphans

Standalone runtime (Only for PM2):

pm2 stop ./pm2-process.json && \
    pm2 flush ft && \
    pm2 delete ./pm2-process.json

👍

---

⚙️ Configuration

🌎 Environment Variables

.env.example:

## --- Environment variable --- ##
ENV=LOCAL
DEBUG=false
# TZ=UTC
# PYTHONDONTWRITEBYTECODE=1


## -- API configs -- ##
FT_API_PORT=8000
# FT_API_CONFIGS_DIR="/etc/rest-fastapi-template"
# FT_API_LOGS_DIR="/var/log/rest-fastapi-template"
# FT_API_DATA_DIR="/var/lib/rest-fastapi-template"
# FT_API_TMP_DIR="/tmp/rest-fastapi-template"
# FT_API_VERSION="1"
# FT_API_PREFIX="/api/v{api_version}"
# FT_API_DOCS_ENABLED=true
# FT_API_DOCS_OPENAPI_URL="{api_prefix}/openapi.json"
# FT_API_DOCS_DOCS_URL="{api_prefix}/docs"
# FT_API_DOCS_REDOC_URL="{api_prefix}/redoc"

---

🧪 Running Tests

To run tests, run the following command:

# Install python test dependencies:
pip install -r ./requirements/requirements.test.txt

# Run tests:
./scripts/test.sh -l -v -c
# Or:
python -m pytest -sv -o log_cli=true

🏗️ Build Docker Image

Before building the docker image, make sure you have installed docker and docker compose.

To build the docker image, run the following command:

# Build docker image:
./scripts/build.sh
# Or:
docker compose build

📝 Generate Docs

To build the documentation, run the following command:

# Install python documentation dependencies:
pip install -r ./requirements/requirements.docs.txt

# Serve documentation locally (for development):
./scripts/docs.sh
# Or:
mkdocs serve -a 0.0.0.0:8000 --livereload

# Or build documentation:
./scripts/docs.sh -b
# Or:
mkdocs build

📚 Documentation

• Docs

---

📑 References

• FastAPI - https://fastapi.tiangolo.com
• Docker - https://docs.docker.com
• Docker Compose - https://docs.docker.com/compose