goFlix - Self-Hosted Media Server

⚠️ Early Development State
This project is in a very early development state. It aims to become a fast, clean, free, and open-source replacement for Plex (and potentially Emby/Jellyfin). Currently, basic registration and authentication work, but there are known issues with HLS streaming that are being actively worked on. After streaming is stabilized, the next priorities are poster update mechanisms and permissions management for multiple users.
See the /screenshots folder for UI previews.

A powerful, self-hosted media server built with Go and PostgreSQL, featuring a modern responsive web interface. goFlix rivals popular platforms like Plex while giving you complete control over your data / media library.

Features

Core Experience

• Admin-first onboarding: The first visit displays a secure admin setup flow before enabling the rest of the app.
• Modern cockpit UI: Global search, real-time status icons, and a collapsible library navigation system inspired by premium media servers.
• PostgreSQL backend paired with a scalable Go API (Gin) for users, profiles, libraries, background jobs, and watch history.
• Library management: Create movie/TV/music/photo libraries, assign folders, configure scanners/agents, and queue scan jobs.
• Responsive Next.js frontend with a dashboard-style layout, continue-watching rail, and hero sections per library.
• In-browser playback with resume progress, watchlists, and ratings.

Future Features

• Native mobile apps (iOS/Android)
• Offline content download
• User forums
• Community features

Screenshots

Home Dashboard

TV Series View

Series Cards

Video Player

Library Management

Settings

Settings - General	Settings - Metadata

Architecture

• Backend: Go (Gin framework)
• Database: PostgreSQL
• Frontend: Next.js (React)
• Deployment: Docker containers

Quick Start

Prerequisites

• Docker and Docker Compose
• PostgreSQL 14+ (or use the provided Docker setup)

Installation

1. Clone the repository:

git clone https://github.com/tuxrem/goflix.git
cd goflix

2. Configure environment variables:

# Create a .env file with own settings (optional)

3. Start with Docker Compose:

docker-compose up -d

Or use the Makefile helpers:

make build   # Build backend & frontend images
make up      # Start postgres + backend + frontend
make logs    # Tail service logs
make down    # Stop containers

4. First-run admin setup:

• Visit http://localhost:3000 - the login page automatically switches to the "Create Admin Account" form until an admin exists.
• After the first admin is created, the standard login form is shown for any additional users (user invite UI coming soon).

Manual Setup

1. Set up PostgreSQL database
2. Start the backend (migrations run automatically on startup):

cd backend
go run cmd/server/main.go

4. Start the frontend:

cd frontend
npm install
npm run dev

Configuration

Environment Variables

Create a .env file in the root directory:

DATABASE_URL=postgres://goflix:goflix@localhost:5432/goflix?sslmode=disable
PORT=8080
JWT_SECRET=super-secret-change-me
MEDIA_PATH=/media
NEXT_PUBLIC_API_URL=http://localhost:8080/api
CORS_ORIGIN=http://localhost:3000
DEBUG=false
NEXT_PUBLIC_DEBUG=false
WRITE_NFO_METADATA=false
TRANSCODER_PATH=ffmpeg
PRODUCT_NAME=goFlix
NEXT_PUBLIC_PRODUCT_NAME=goFlix

• DATABASE_URL: PostgreSQL connection string
• JWT_SECRET: Secret key for JWT tokens (must be strong in production)
• MEDIA_PATH: Host path mounted into the backend container for media scanning/streaming
• NEXT_PUBLIC_API_URL: Frontend -> backend base URL
• CORS_ORIGIN: Allowed origin for browser requests
• DEBUG: Enables verbose backend logging and relaxed guards when true
• NEXT_PUBLIC_DEBUG: Enables verbose client-side logging when true
• WRITE_NFO_METADATA: When true, missing season/episode .nfo files are generated alongside your media
• TRANSCODER_PATH: Location of the FFmpeg binary used for adaptive streaming

Project Structure

goflix/
├── backend/          # Go backend API
│   ├── cmd/         # Application entry points
│   ├── internal/    # Internal packages
│   │   ├── api/     # HTTP handlers
│   │   ├── config/  # Configuration
│   │   ├── database/# Database migrations
│   │   └── models/  # Data models
│   └── Dockerfile
├── frontend/         # Next.js frontend
│   ├── app/         # Next.js app directory
│   ├── components/  # React components
│   ├── lib/         # Utilities
│   └── Dockerfile
├── docs/            # Documentation
├── media/           # Media files directory (mount your media here)
├── docker-compose.yml
└── Makefile         # Convenience commands

Documentation

See docs/ for detailed references:

• API endpoints - authentication, media, libraries, watchlists, ratings.
• Setup guide - Docker vs manual install, media ingestion, troubleshooting.
• Database schema lives in backend/internal/database/migrations.go and now covers libraries, paths, and scan jobs.
• Mobile client integration & transcoder docs are being tracked for the next milestone.

Contributing

We would greatly appreciate all help to make this project something really cool! 🚀

This is an open-source project in early development, and we welcome contributions of all kinds:

• Bug Reports: Found an issue? Please open an issue with details
• Feature Requests: Have ideas for improvements? We'd love to hear them
• Code Contributions: Pull requests are welcome! Check out the codebase and pick an area to improve
• Documentation: Help us improve docs, add examples, or translate content
• Testing: Help us test features and report bugs
• Feedback: Share your thoughts and experiences using goFlix

Every contribution, no matter how small, helps make goFlix better. Together, we can build a fast, clean, and powerful alternative to existing media server solutions.

Thank you for your interest and support! 🙏

License

MIT License