Installation - Water Quality Backend API

This comprehensive guide covers all installation methods for the Water Quality Backend API, from local development to production Docker deployment.

Prerequisites

Before installing the Water Quality Backend API, ensure you have the following:

System Requirements

Python 3.9 or higher (Python 3.12 recommended)
pip 21.0+ for package management
Git for version control
Virtual environment support (built into Python 3.3+)

Optional Tools

Docker (for containerized deployment)
Docker Compose (for multi-container orchestration)
Postman or curl (for API testing)

External Services

You’ll need accounts and credentials for:

Firebase (Required)
- Firebase Realtime Database
- Firebase Admin SDK credentials
- Get started at firebase.google.com
Weather API (Optional)
- For weather data integration
OneSignal (Optional)
- For push notifications
- Sign up at onesignal.com
Resend (Optional)
- For email notifications
- Sign up at resend.com
OpenRouter (Optional)
- For AI-powered analysis
- Sign up at openrouter.ai
GitHub OAuth (Optional)
- For social authentication
- Create an OAuth App at github.com/settings/developers

Only Firebase credentials are required to get started. Other services can be configured later based on your needs.

Local Installation

Clone the Repository

Start by cloning the project from your Git repository:

git clone <repository-url>
cd water-quality-backend

Verify the repository structure:

ls -la

You should see:

app/ - Application source code
main.py - Application entry point
requirements.txt - Python dependencies
.env.example - Environment variable template
Dockerfile - Docker configuration

Create Virtual Environment

Create an isolated Python environment:

python -m venv .venv

Or using Python 3 explicitly:

python3 -m venv .venv

Activate the virtual environment:

source .venv/bin/activate

Verify activation:

which python  # Linux/macOS
where python  # Windows

The output should point to the Python binary inside .venv/.

Install Dependencies

Upgrade pip to the latest version:

pip install --upgrade pip

Install all required packages:

pip install -r requirements.txt

This installs:Core Framework

fastapi[all]>=0.100.0 - Web framework with all extras
uvicorn - ASGI server (included with FastAPI)
python-dotenv - Environment variable management

Authentication & Security

firebase-admin - Firebase Admin SDK
PyJWT - JSON Web Token handling
passlib[bcrypt] - Password hashing

Data Science & AI

pandas - Data manipulation
numpy - Numerical computing
scikit-learn - Machine learning
pydantic-ai-slim[openai] - AI model integration
matplotlib>=3.8.0 - Data visualization
fpdf2 - PDF report generation

Real-time & Notifications

python-socketio[asyncio] - WebSocket support
onesignal-python-api - Push notifications
resend - Email delivery

Monitoring

prometheus-client==0.23.1 - Metrics and monitoring

Testing (optional, included in requirements.txt)

pytest>=7.0.0 - Testing framework
pytest-asyncio>=0.21.0 - Async test support
pytest-cov>=4.0.0 - Code coverage
httpx>=0.24.0 - HTTP client for tests

Installation may take several minutes due to the large number of dependencies, especially data science packages.

Install Development Dependencies (Optional)

For running tests and development tools:

pip install -r requirements-test.txt

Configure Environment Variables

Create your environment configuration file:

cp .env.example .env

Open .env in your text editor and configure the following variables:

Required Configuration

.env

# JWT Secret Key (Required)
SECRET_KEY=your_secret_key_here

# Firebase API Configuration (Required)
FIREBASE_API_KEY=your_firebase_api_key
FIREBASE_REALTIME_URL=https://your-project.firebaseio.com

# Firebase Admin SDK Credentials (Required)
FIREBASE_TYPE=service_account
FIREBASE_PROJECT_ID=your_project_id
FIREBASE_PRIVATE_KEY_ID=your_private_key_id
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour\nPrivate\nKey\nHere\n-----END PRIVATE KEY-----\n"
FIREBASE_CLIENT_EMAIL=[email protected]
FIREBASE_CLIENT_ID=123456789012345678901
FIREBASE_AUTH_URI=https://accounts.google.com/o/oauth2/auth
FIREBASE_TOKEN_URI=https://oauth2.googleapis.com/token
FIREBASE_AUTH_PROVIDER_X509_CERT_URL=https://www.googleapis.com/oauth2/v1/certs
FIREBASE_CLIENT_X509_CERT_URL=https://www.googleapis.com/robot/v1/metadata/x509/firebase-adminsdk-xxxxx%40your-project.iam.gserviceaccount.com
FIREBASE_UNIVERSE_DOMAIN=googleapis.com

Generate SECRET_KEY

Generate a cryptographically secure secret key:

python -c 'import secrets; print(secrets.token_hex(32))'

Copy the output and use it as your SECRET_KEY.

Optional Configuration

.env

# Weather API
WEATHER_API_KEY=your_weather_api_key

# OneSignal Push Notifications
ONESIGNAL_APP_ID=your_onesignal_app_id
ONESIGNAL_API_KEY=your_onesignal_api_key

# Email Service (Resend)
RESEND_API_KEY=your_resend_api_key

# AI Analysis (OpenRouter)
OPEN_ROUTER_KEY=your_open_router_key
OPEN_ROUTER_MODEL=openai/gpt-4-turbo

# GitHub OAuth
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GITHUB_CALLBACK_URL=http://localhost:8000/auth/github/callback

# Frontend Configuration
FRONTEND_ORIGIN=http://localhost:3000

# Mobile Deep Link
APP_DEEP_LINK=aquaminds://login-success

# OAuth State Secret
STATE_SECRET=your_state_secret_here

Security Best Practices:

Never commit .env to version control
Use different credentials for development and production
Rotate secrets regularly
Keep FIREBASE_PRIVATE_KEY properly formatted with \n for newlines

Set Up Firebase

Create a Firebase Project

Go to Firebase Console
Click “Add project” and follow the wizard
Enable Realtime Database:
- Navigate to Build > Realtime Database
- Click “Create Database”
- Choose your location
- Start in test mode for development (update rules for production)

Get Firebase Admin SDK Credentials

In Firebase Console, go to Project Settings (gear icon)
Navigate to Service accounts tab
Click Generate new private key
Download the JSON file
Extract the values and add them to your .env file:

{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "abc123...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "firebase-adminsdk@...",
  "client_id": "123456789...",
  // ... other fields
}

When copying private_key to .env, ensure newlines are escaped as \n.

Get Firebase Web API Key

In Project Settings, go to General tab
Scroll to Your apps section
If no web app exists, click “Add app” and select Web
Copy the apiKey value to FIREBASE_API_KEY in .env

Get Realtime Database URL

Navigate to Realtime Database in Firebase Console
Copy the database URL (e.g., https://your-project.firebaseio.com)
Add it to FIREBASE_REALTIME_URL in .env

Run the Development Server

Start the FastAPI development server:

fastapi dev app

The server will start on http://localhost:8000 with:

Auto-reload enabled (restarts on code changes)
Debug mode active
Interactive docs at /docs

You should see:

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [xxxxx] using WatchFiles
INFO:     Started server process [xxxxx]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Production Server

For production, use the production entry point:

python main.py

Or run Uvicorn directly with production settings:

uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4

Verify Installation

Test the API to ensure everything is working:

1. Check API Root

curl http://localhost:8000/

Expected response:

{"message": "API"}

2. Access Interactive Docs

Open http://localhost:8000/docs in your browser.You should see the Swagger UI with all available endpoints.

3. Test Registration Endpoint

curl -X POST http://localhost:8000/auth/register/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "username": "testuser",
    "password": "TestPass123!",
    "phone": "+1234567890"
  }'

Expected response:

{"message": "Registered successfully"}

4. Check Metrics Endpoint

curl http://localhost:8000/metrics

You should see Prometheus metrics output.

If all tests pass, your installation is complete and the API is ready to use!

Docker Installation

Deploy the API in a containerized environment for consistency and portability.

Using Docker

Build the Docker Image

Build the container image using the provided Dockerfile:

docker build -t water-quality-backend .

The Dockerfile:

Uses Python 3.12 slim base image
Installs system dependencies (gcc, build tools)
Copies and installs Python dependencies
Creates a non-root user for security
Exposes port 8000

The build process may take 5-10 minutes on the first run due to downloading and compiling dependencies.

Run the Container

Start the container with environment variables:

docker run -d \
  --name water-quality-api \
  -p 8000:8000 \
  --env-file .env \
  water-quality-backend

Or run in interactive mode:

docker run -it \
  --name water-quality-api \
  -p 8000:8000 \
  --env-file .env \
  water-quality-backend

View Logs

docker logs -f water-quality-api

Stop the Container

docker stop water-quality-api

Remove the Container

docker rm water-quality-api

Using Docker Compose

For more complex deployments with multiple services:

Review docker-compose.yml

The project includes a docker-compose.yml file:

docker-compose.yml

version: '3.8'

services:
  api:
    build: .
    ports:
      - "8000:8000"
    env_file:
      - .env
    restart: unless-stopped
    volumes:
      - ./app:/app/app

Start Services

Launch all services with Docker Compose:

docker-compose up -d

View logs:

docker-compose logs -f

Stop services:

docker-compose down

Rebuild and restart:

docker-compose up -d --build

Docker deployment is recommended for production environments as it ensures consistent runtime across different systems.

Testing the Installation

Run the comprehensive test suite to verify everything works:

pip install -r requirements-test.txt
pytest

Run with coverage report:

pytest --cov=app --cov-report=html

Run specific test modules:

pytest tests/features/auth/  # Test authentication
pytest tests/features/meters/  # Test meter management

The test suite includes unit tests, integration tests, and API endpoint tests across all features.

Troubleshooting

Python Version Issues

Problem: python: command not found or wrong Python version Solution:

# Check Python version
python --version
python3 --version

# Use python3 explicitly if needed
python3 -m venv .venv
python3 -m pip install -r requirements.txt

Dependency Installation Failures

Problem: Error installing pandas, numpy, or scikit-learn Solution: Install system build tools:

sudo apt-get update
sudo apt-get install python3-dev build-essential

Firebase Connection Errors

Problem: Firebase app initialization failed Solution:

Verify all Firebase credentials in .env
Check FIREBASE_PRIVATE_KEY formatting (must have \n for newlines)
Ensure Firebase Realtime Database is created and accessible
Verify service account has proper permissions

Port Already in Use

Problem: Address already in use: port 8000 Solution:

# Find process using port 8000
lsof -ti:8000  # macOS/Linux
netstat -ano | findstr :8000  # Windows

# Kill the process or use a different port
fastapi dev app --port 8001

Import Errors

Problem: ModuleNotFoundError when starting the server Solution:

Ensure virtual environment is activated
Reinstall dependencies: pip install -r requirements.txt
Check you’re in the correct directory (project root)

If you encounter persistent issues, check that your .env file doesn’t have syntax errors and all required variables are set.

Next Steps

Now that installation is complete:

Quickstart Guide

Make your first API call and authenticate a user

Authentication

Learn about JWT tokens, OAuth, and password management

API Reference

Explore all available endpoints and data models

Deployment Guide

Deploy to production with best practices

Production Considerations

Before deploying to production:

Environment Variables
- Use production Firebase credentials
- Generate new SECRET_KEY and STATE_SECRET
- Update FRONTEND_ORIGIN to production URL
Security
- Update Firebase Realtime Database rules
- Enable HTTPS/TLS
- Configure CORS properly
- Use environment-specific secrets
Performance
- Run with multiple Uvicorn workers
- Set up reverse proxy (Nginx)
- Enable caching where appropriate
- Monitor with Prometheus metrics
Monitoring
- Set up log aggregation
- Configure alerting (Prometheus/AlertManager)
- Monitor /metrics endpoint

For detailed production deployment instructions, see the Deployment Guide.

Get Started

Guides

Features

​Prerequisites

​System Requirements

​Optional Tools

​External Services

​Local Installation

​Install Development Dependencies (Optional)

​Required Configuration

​Generate SECRET_KEY

​Optional Configuration

​Create a Firebase Project

​Get Firebase Admin SDK Credentials

​Get Firebase Web API Key

​Get Realtime Database URL

​Production Server

​1. Check API Root

​2. Access Interactive Docs

​3. Test Registration Endpoint

​4. Check Metrics Endpoint

​Docker Installation

​Using Docker

​View Logs

​Stop the Container

​Remove the Container

​Using Docker Compose

​Testing the Installation

​Troubleshooting

​Python Version Issues

​Dependency Installation Failures

​Firebase Connection Errors

​Port Already in Use

​Import Errors

​Next Steps

Quickstart Guide

Authentication

API Reference

Deployment Guide

​Production Considerations

Build docs developers (and LLMs) love

Prerequisites

System Requirements

Optional Tools

External Services

Local Installation

Install Development Dependencies (Optional)

Required Configuration

Generate SECRET_KEY

Optional Configuration

Create a Firebase Project

Get Firebase Admin SDK Credentials

Get Firebase Web API Key

Get Realtime Database URL

Production Server

1. Check API Root

2. Access Interactive Docs

3. Test Registration Endpoint

4. Check Metrics Endpoint

Docker Installation

Using Docker

View Logs

Stop the Container

Remove the Container

Using Docker Compose

Testing the Installation

Troubleshooting

Python Version Issues

Dependency Installation Failures

Firebase Connection Errors

Port Already in Use

Import Errors

Next Steps

Production Considerations