FastAPI Template

This is a template repository for FastAPI web service projects.

✨ Features

• FastAPI
• REST API
• Web service
• Microservice
• Project structure
• Boilerplate/template
• Best practices
• Configuration
• Tests
• Build
• Scripts
• Examples
• Documentation
• CI/CD
• Docker and docker compose

🧩 Template

• You can use this template repository as reference to create a new repository with the same structure or clone the repository to start a new project. It will help you to organize your project structure and files. It works out of the box for most REST API service projects.

• You can customize (remove, modify or add) the files and directories as needed to meet your project requirements.

• If you want to use the template repository directly, just click the Use this template button and follow the instructions.

• You can use cookiecutter to generate a new project from cookiecutter branch:

  # Clone the cookiecutter branch:
  git clone -b cookiecutter https://github.com/bybatkhuu/rest.fastapi-template.git
  
  # Install cookiecutter:
  pip install cookiecutter
  
  # Generate a new project from the cookiecutter template:
  cookiecutter -f ./rest.fastapi-template

---

🐤 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.9) and pip (>= 23):
  • [RECOMMENDED] Miniconda (v3)
  • [arm64/aarch64] Miniforge (v3)
  • [Python virutal environment] venv

[OPTIONAL] For DEVELOPMENT environment:

• Install git
• Setup an SSH key (video tutorial)

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 [email protected]: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

4. 🌎 Configure environment variables

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

OPTION A. [RECOMMENDED] For docker runtime [5.A]

# Copy '.env.example' file to '.env' file:
cp -v ./.env.example ./.env

# Edit environment variables to fit in your environment:
nano ./.env

OPTION B. For standalone runtime [5.B ~ 5.F]

# Copy '.env.example' file to '.env' file:
cp -v ./.env.example ./src/.env

# Edit environment variables to fit in your environment:
nano ./src/.env

5. 🏁 Start the server

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

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 --tail 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 script:

cd src
python -u ./main.py

OPTION D. Run server as python module:

python -u -m src.api

# Or:
cd src
python -u -m api

OPTION E. Run with uvicorn cli:

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


# Or:
cd src
uvicorn main:app --host="0.0.0.0" --port=8000 --no-access-log --no-server-header --proxy-headers --forwarded-allow-ips="*"

# For DEVELOPMENT:
uvicorn main:app --host="0.0.0.0" --port=8000 --no-access-log --no-server-header --proxy-headers --forwarded-allow-ips="*" --reload --reload-include="*.yml" --reload-include=".env"

OPTION F. Run with fastapi cli:

fastpi run src/main.py --host=[BIND_HOST] --port=[PORT]
# For example:
fastapi run src/main.py --port=8000

# For DEVELOPMENT:
fastapi dev src/main.py --host="0.0.0.0" --port=8000


# Or:
cd src
fastapi run --port=8000

# For DEVELOPMENT:
fastapi dev --host="0.0.0.0" --port=8000

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=Asia/Seoul


## -- API configs -- ##
FT_API_PORT=8000
# FT_API_LOGS_DIR="/var/log/rest.fastapi-template"
# FT_API_DATA_DIR="/var/lib/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"

🔧 Command arguments

You can customize the command arguments to debug or run the service with different commands.

compose.override.yml:

    command: ["/bin/bash"]
    command: ["-b", "pwd && ls -al && /bin/bash"]
    command: ["-b", "python -u -m api"]
    command: ["-b", "uvicorn main:app --host=0.0.0.0 --port=${FT_API_PORT:-8000} --no-access-log --no-server-header --proxy-headers --forwarded-allow-ips='*'"]

---

🧪 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

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

📚 Documentation

• Docs
• Home

Getting Started

• Prerequisites
• Installation
• Quick start
• Configuration
• Examples

API Documentation

• openapi.json
• Error Codes

Development

• Test
• Build
• Docs
• Scripts
• CI/CD
• File Structure
• Sitemap
• Related projects
• Roadmap
• Contributing

Research

• Reports
• Benchmarks
• References

Release Notes

Blog

About

• FAQ
• Authors
• Contact
• License

---

📑 References

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