Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AngelAmoSanchez/TFG-RaspberryPi-BLE/llms.txt

Use this file to discover all available pages before exploring further.

The cloud backend is a FastAPI application that receives BLE detection data from Raspberry Pi agents, stores it in PostgreSQL, and exposes a REST API with real-time WebSocket updates. You can run it with Docker Compose (recommended) or directly with Python 3.11.

​
Prerequisites

Docker setup

  • Docker Engine 24+
  • Docker Compose v2 (docker compose command)

Manual setup

  • Python 3.11+
  • PostgreSQL 14+
  • pip

​
Docker Compose quickstart

Docker Compose starts both the PostgreSQL database and the backend API in a single command. The backend waits for the database health check to pass before starting.
1

Clone the repository and enter the backend directory

git clone https://github.com/AngelAmoSanchez/TFG-RaspberryPi-BLE.git
cd TFG-RaspberryPi-BLE/backend-cloud
2

Copy and edit the environment file

cp .env.example.prod .env
At minimum, set SECRET_KEY before running in production. For local development the defaults work as-is.
3

Start the stack

docker compose up -d
This builds the image from the Dockerfile and starts two services:
services:
  postgres:
    image: postgres:14-alpine
    container_name: tfg-postgres
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: tfg_detections
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  backend:
    build: .
    container_name: tfg-backend
    environment:
      DATABASE_URL: postgresql+asyncpg://postgres:postgres@postgres:5432/tfg_detections
      ENVIRONMENT: development
      DEBUG: "true"
      MQTT_ENABLED: "false"
    ports:
      - "8000:8000"
    depends_on:
      postgres:
        condition: service_healthy
    volumes:
      - .:/app
    command: uvicorn src.api.main:app --host 0.0.0.0 --port 8000 --reload
4

Run database migrations

docker compose exec backend alembic upgrade head
5

Verify the backend is running

curl http://localhost:8000/health
Use make docker-up and make docker-down as shortcuts for docker compose up -d and docker compose down.

​
Manual Python setup

Use this approach when you want to run the backend directly on the host, for example during development or when Docker is not available.
1

Create a virtual environment

python3.11 -m venv venv
source venv/bin/activate
2

Install dependencies

pip install -r requirements.txt
Key packages installed:
fastapi==0.109.0
uvicorn[standard]==0.27.0
sqlalchemy==2.0.25
asyncpg==0.29.0
psycopg2-binary==2.9.9
pydantic==2.5.3
pydantic-settings==2.1.0
paho-mqtt==1.6.1
alembic==1.13.1
3

Configure environment variables

cp .env.example.prod .env
# Edit .env — set DATABASE_URL to point to your local PostgreSQL instance
4

Run database migrations

alembic upgrade head
Alembic reads alembic.ini and applies all pending migrations from the migrations/ directory. The sqlalchemy.url in alembic.ini is overridden at runtime by the DATABASE_URL environment variable.
5

Start the server

bash run.sh
The backend requires a running PostgreSQL instance before it starts. If the database is unreachable, init_db() will fail on startup.

​
Database migrations

The project uses Alembic with the migrations/ directory as the script location (configured in alembic.ini).
CommandDescription
alembic upgrade headApply all pending migrations
alembic downgrade -1Roll back the last migration
make upgradeShortcut for alembic upgrade head
make migrate msg="description"Auto-generate a new migration from model changes

​
Health check and root endpoint

Once running, two diagnostic endpoints are available without authentication. GET /health — confirms the server is up and returns the current WebSocket connection count: 
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00+01:00",
  "websocket_connections": 0
}
GET / — returns application metadata: 
{
  "app": "TFG Bluetooth Detection Backend",
  "version": "v1",
  "environment": "development",
  "status": "running"
}
All API routes are mounted under /api/v1, for example GET /api/v1/detections.

Build docs developers (and LLMs) love

Get started for freeTalk to us