Skip to content

🏃 Quick Start

1. 🌎 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

2. 🏁 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 --tail 100

Standalone runtime

[IMPORTANT] Before running, make sure database is up and running.

Run alembic migration to create or update database schema to the latest version:

# 1. Create a symbolic link to '.env' file in './src/.env' file:
ln -s -v ../.env ./src/.env

# 2. Run alembic migration:
./scripts/migrate.sh up
# Or:
cd ./src
alembic -x data=true upgrade head
cd ..

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 fot

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="*"

Run directly from src directory

# 1. Enter into src directory:
cd src

# 2. Run server:
# 2.a. Run as python module:
python -u -m api

# 2.b. Or run with uvicorn cli:
uvicorn api.main:app --host="0.0.0.0" --port=8000 --no-access-log --no-server-header --proxy-headers --forwarded-allow-ips="*"
# For DEVELOPMENT:
uvicorn api.main:app --host="0.0.0.0" --port=8000 --no-access-log --no-server-header --proxy-headers --forwarded-allow-ips="*" --reload

# 2.c. Or run with fastapi cli:
fastapi run api/main.py --port=8000 --forwarded-allow-ips="*"
# For DEVELOPMENT:
fastapi dev api/main.py --host="0.0.0.0" --port=8000 --forwarded-allow-ips="*"

3. ✅ 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:

4. 🛑 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 fot && \
    pm2 delete ./pm2-process.json

👍