🌌 NebulaStream

A production-ready, self-hosted media server with AI-powered discovery and watch party support.

🏗️ Architecture

nebulastream/
├── backend/          # FastAPI Python service
├── frontend/         # Next.js TypeScript app
├── worker/           # Celery task worker (shared backend code)
├── nginx/            # Reverse proxy config
├── docker-compose.yml
├── .env.example
└── Makefile

🚀 Quick Start

Prerequisites

• Docker & Docker Compose v2
• Make (optional but recommended)

1. Clone and configure

git clone https://github.com/mxl1qr/NebulaStream.git
cd nebulastream
cp .env.example .env
# Edit .env and enter your Supabase connection string and other secrets

2. Start all services

make up
# or: docker compose up -d --build

3. Run migrations

make migrate
# or: docker compose exec backend alembic upgrade head

4. Seed demo data

make seed
# or: docker compose exec backend python -m scripts.seed

5. Access

Service	URL
Frontend	http://localhost:3000
API	http://localhost:8000
API Docs	http://localhost:8000/docs
Meilisearch UI	http://localhost:7700

🛠️ Makefile Commands

make up          # Start all services
make down        # Stop all services
make build       # Rebuild images
make logs        # Tail logs
make migrate     # Run Alembic migrations
make makemig     # Create new migration
make seed        # Seed demo data
make test        # Run backend tests
make lint        # Run linters
make shell       # Open backend shell

🔐 Default Credentials (after seed)

Role	Email	Password
Admin	admin@nebula.local	nebula_admin
User	user@nebula.local	nebula_user
Guest	guest@nebula.local	nebula_guest

📦 Tech Stack

Layer	Technology
Backend	FastAPI + SQLAlchemy + Alembic
Frontend	Next.js 15 + TypeScript + Tailwind
Database	Supabase (Managed PostgreSQL)
Cache	Redis 7
Queue	Celery 5
Search	Meilisearch
Media	FFmpeg + HLS
Auth	JWT (access + refresh) + RBAC
Deployment	Docker Compose