Skip to content

README.md

Latest commit

 

History

History
165 lines (114 loc) · 3.88 KB

README.md

File metadata and controls

165 lines (114 loc) · 3.88 KB

BetterSurf Internet-Provider Comparison

Python Version FastAPI

Table of Contents

  1. 📌 About
  2. 🚀 Features
  3. 🛠️ Prerequisites
  4. 🏁 Getting Started
  5. 🐳 Dockerized Deployment
  6. 📚 API Reference
  7. 🔒 CORS & HTTPS

📌 About

BetterSurf is a FastAPI-based service that aggregates and compares internet-provider offers from multiple vendors.
It exposes both REST and WebSocket endpoints and comes fully Dockerized for easy deployment.

🚀 Features

  • 🔄 HTTP & WebSocket endpoints for real-time offer streaming
  • 🛡️ Health-check & graceful shutdown
  • 🔌 Circuit-breaker integration per provider
  • ☁️ CORS middleware preconfigured
  • 📜 Auto-generated OpenAPI docs (/docs & /redoc)
  • 🐳 Docker & Docker-Compose setup ready for production
  • ⚙️ Env-based settings with secure credential management

🛠️ Prerequisites

  • Python 3.12
  • Docker & Docker-Compose (if using containers)
  • ngrok or equivalent (for HTTPS tunneling)

🏁 Getting Started

Clone the Repo

git clone https://github.com/jaylann/gendev.git
cd bettersurf

Install Dependencies

We use uv for ultra-fast installs. Fallback to pip if you prefer:

# Using uv
uv pip install --system -r requirements.txt

# Or with pip
pip install --no-cache-dir -r requirements.txt

Configuration

  1. Copy .env.example to .env

  2. Fill in your API keys and credentials:

    # .env
VERBYNDICH_API_KEY=YOUR_API_KEY_HERE
SERVUSSPEED_USERNAME=YOUR_USERNAME_HERE
SERVUSSPEED_PASSWORD=YOUR_PASSWORD_HERE
PINGPERFECT_CLIENT_ID=YOUR_CLIENT_ID_HERE
PINGPERFECT_SECRET=YOUR_SECRET_HERE
WEBWUNDER_API_KEY=YOUR_API_KEY_HERE
BYTEME_API_KEY=YOUR_API_KEY_HERE

  3. (Optional) Override any service endpoints if needed as well as cache ttl.

Run Locally

uvicorn main:app --reload --host 0.0.0.0 --port 8000

🐳 Dockerized Deployment

Build and run with Docker Compose:

docker-compose up --build -d
  • The FastAPI app listens on 8000 internally.
  • Nginx proxies HTTP (/) and WebSocket (/ws/) traffic on port 80.
  • Built-in health-check ensures the app is ready before Nginx routes traffic.

📚 API Reference

Refer to the OpenAPI docs for full schema.

🔒 CORS & HTTPS

CORS Settings

By default, CORS is wide open for development:

app.add_middleware(
  CORSMiddleware,
  allow_origins=["*"],
  allow_methods=["GET","POST","OPTIONS"],
  allow_headers=["*"],
)

⚠️ Production: Restrict allow_origins and allow_methods to your front-end domains.

HTTPS with ngrok

To expose your local server over HTTPS for testing:

  1. Install ngrok.

  2. Start your FastAPI app on port 8000.

  3. In a new terminal, run:

    ngrok http 8000

  4. Copy the generated https://…ngrok.io URL and use it to call your API endpoints securely.

Made with ❤️ by Justin Lanfermann