Watchyfin

Self-hosted Jellyfin companion with a Python/FastAPI backend and a React frontend.

Docker (recommended)

The stack runs three containers: MongoDB, the FastAPI backend, and the Nginx-served React frontend.

Requirements

• Docker + Docker Compose

Run

docker compose up --build

• Frontend: http://localhost:8080
• Backend API: http://localhost:8001/api

Configuration

The backend uses the following environment variables (already set in docker-compose.yml):

• MONGO_URL: Mongo connection string (default: mongodb://mongo:27017)
• DB_NAME: Database name (default: watchyfin)

Rebuild with a different backend URL

If you need the frontend to call a different backend URL, override the build arg:

docker compose build \
  --build-arg REACT_APP_BACKEND_URL=http://your-host:8001 frontend

Local development (without Docker)

Backend

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export MONGO_URL=mongodb://localhost:27017
export DB_NAME=watchyfin
uvicorn server:app --host 0.0.0.0 --port 8001

Frontend

cd frontend
yarn install
REACT_APP_BACKEND_URL=http://localhost:8001 yarn start