wjones/pgsql-jellyfin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
multi-instance-testing
pgsql-jellyfin/docs/README.md
T
wjones 77e30685bb Complete multi-instance support: Phases 3–6 & deployment 
- Implements Phases 3–6: session isolation, cache coordination, primary election, and file system monitor coordination for Jellyfin with PostgreSQL.
- Adds new database entities (Instance, DistributedLock, FileSystemChange) and EF model configurations.
- Includes SQL migration scripts and EF migration for all required tables, columns, and helper functions.
- Updates Device entity and JellyfinDbContext for multi-instance tracking.
- Integrates new DI services for instance registry, distributed locks, cache coordinator, and primary election.
- Adds publishing profiles (Win/Linux/FrameworkDependent) and automation script for deployment.
- Extensive documentation for architecture, setup, and publishing.
- All changes are backward compatible and build successfully.
2026-03-05 16:10:26 -05:00

389 lines
15 KiB
Markdown
Raw Permalink Blame History

# Jellyfin with PostgreSQL Support
**The Free Software Media System - Now with Enterprise Database Backend**
---
## 🚀 What's New in This Fork?
This is a **PostgreSQL-enabled fork** of Jellyfin that replaces SQLite with PostgreSQL for improved performance, scalability, and reliability.
### ✨ Key Features
- ✅ **PostgreSQL Database Backend** - Full migration from SQLite
- ✅ **Improved Performance** - Better handling of large libraries
- ✅ **Enterprise Scalability** - Replication and clustering support
- ✅ **Professional Backups** - pgBackRest integration
- ✅ **OS-Specific Configuration** - Auto-configuration for Windows/Linux/macOS
- ✅ **Windows Installer** - Professional installer with PostgreSQL wizard
- ✅ **Centralized Build** - All DLLs in `lib` folder
---
## 📚 Quick Navigation
- [Quick Start](#quick-start)
- [Installation](#installation)
- [PostgreSQL Setup](#postgresql-setup)
- [Configuration](#configuration)
- [Building](#building-from-source)
- [Creating Installer](#creating-an-installer)
- [Migration](#migration-guide)
- [Troubleshooting](#troubleshooting)
- [Documentation](#documentation)
---
## 🎯 Quick Start
### Windows Installer
```powershell
# Run JellyfinSetup-PostgreSQL-11.0.0.exe
# Follow wizard for PostgreSQL setup
```
### From Source
```bash
git clone https://gitea.wpjones.com/wjones/pgsql-jellyfin.git
cd pgsql-jellyfin
dotnet build --configuration Release
cd lib/Release/net11.0
dotnet jellyfin.dll
```
📖 See [INSTALLER_QUICK_START.md](./docs/INSTALLER_QUICK_START.md) or [QUICKSTART_POSTGRESQL.md](./docs/QUICKSTART_POSTGRESQL.md)
---
## 📦 Installation
### Prerequisites
- **.NET 11 Runtime** - [Download](https://dotnet.microsoft.com/download/dotnet/11.0)
- **PostgreSQL 12+** - [Download](https://www.postgresql.org/download/)
- **FFmpeg** - [Jellyfin builds](https://github.com/jellyfin/jellyfin-ffmpeg)
### Install from Installer (Windows)
1. Download `JellyfinSetup-PostgreSQL-11.0.0.exe`
2. Run installer, select options
3. Configure PostgreSQL (or skip for later)
4. Open http://localhost:8096
📖 Full guide: [INSTALLER_GUIDE.md](./docs/INSTALLER_GUIDE.md)
### Install from Source
**Windows:**
```powershell
dotnet build Jellyfin.Server --configuration Release
cd lib\Release\net11.0
jellyfin.exe
```
**Linux:**
```bash
dotnet build Jellyfin.Server --configuration Release
cd lib/Release/net11.0
./jellyfin
```
---
## 🗄️ PostgreSQL Setup
### Quick Install
**Windows:**
```powershell
winget install PostgreSQL.PostgreSQL
```
**Linux:**
```bash
sudo apt install postgresql postgresql-contrib
```
### Create Database
```sql
psql -U postgres
CREATE USER jellyfin WITH PASSWORD 'your_password';
CREATE DATABASE jellyfin OWNER jellyfin;
GRANT ALL PRIVILEGES ON DATABASE jellyfin TO jellyfin;
\q
```
### Configure Connection
Edit `startup.json`:
```json
{
"DatabaseProvider": "Postgres",
"ConnectionStrings": {
"DefaultConnection": "Host=localhost;Database=jellyfin;Username=jellyfin;Password=your_password"
}
}
```
📖 Full guide: [QUICKSTART_POSTGRESQL.md](./docs/QUICKSTART_POSTGRESQL.md)
---
## ⚙️ Configuration
### OS-Specific Defaults
`startup.json` is auto-configured per platform:
- **Windows:** `C:/ProgramData/jellyfin`
- **Linux:** `/var/lib/jellyfin`, `/etc/jellyfin`
- **macOS:** `~/Library/Application Support/jellyfin`
### Priority Order
1. Command-line arguments
2. Environment variables
3. startup.json
4. Built-in defaults
📖 Docs: [OS_SPECIFIC_STARTUP_CONFIG.md](./docs/OS_SPECIFIC_STARTUP_CONFIG.md), [STARTUP_JSON_VERIFICATION.md](./docs/STARTUP_JSON_VERIFICATION.md)
---
## 🔨 Building from Source
```bash
git clone https://gitea.wpjones.com/wjones/pgsql-jellyfin.git
cd pgsql-jellyfin
dotnet restore
dotnet build --configuration Release
# Output: lib/Release/net11.0/
```
📖 See [CENTRALIZED_LIB_FOLDER.md](./docs/CENTRALIZED_LIB_FOLDER.md)
---
## 📦 Creating an Installer
```powershell
# 1. Install Inno Setup
winget install JRSoftware.InnoSetup
# 2. Build
.\build-installer.ps1
# 3. Result
# installer-output\JellyfinSetup-PostgreSQL-11.0.0.exe
```
Features:
- Windows Service installation
- Firewall rules
- PostgreSQL wizard
- .NET runtime check
📖 Guides: [INSTALLER_QUICK_START.md](./docs/INSTALLER_QUICK_START.md), [INSTALLER_GUIDE.md](./docs/INSTALLER_GUIDE.md)
---
## 🔄 Migration Guide
### SQLite to PostgreSQL
```bash
# 1. Backup
cp jellyfin.db jellyfin-backup.db
# 2. Set up PostgreSQL
# 3. Update startup.json
# 4. Run migration
dotnet run --project Jellyfin.Server -- --migrate-database
```
📖 See [POSTGRESQL_MIGRATION_COMPLETE.md](./docs/POSTGRESQL_MIGRATION_COMPLETE.md)
---
## 🔧 Troubleshooting
### PostgreSQL Connection
```bash
# Check status
sudo systemctl status postgresql
# Test connection
psql -U jellyfin -d jellyfin
```
### Service Issues
```bash
# Check logs
tail -f /var/log/jellyfin/log_*.txt
```
📖 Full guides: [POSTGRESQL_TROUBLESHOOTING.md](./docs/POSTGRESQL_TROUBLESHOOTING.md), [TROUBLESHOOTING_EF_PENDING_CHANGES.md](./docs/TROUBLESHOOTING_EF_PENDING_CHANGES.md)
---
## 📖 Documentation
### 🚀 Getting Started
- **[START_HERE.md](./docs/START_HERE.md)** - **Start here!** Complete quick start guide
- **[QUICK_REFERENCE.md](./docs/QUICK_REFERENCE.md)** - Quick command reference
- **[COMPLETE-SESSION-SUMMARY.md](./docs/COMPLETE-SESSION-SUMMARY.md)** - All recent fixes and improvements
### ⚙️ Configuration & Setup
- **[database-configuration-examples.md](./docs/database-configuration-examples.md)** - **Complete database configuration reference**
- **[library-monitor-delay-configuration.md](./docs/library-monitor-delay-configuration.md)** - **Configure file system monitoring delays** (NEW)
- [OS_SPECIFIC_STARTUP_CONFIG.md](./docs/OS_SPECIFIC_STARTUP_CONFIG.md) - Platform-specific configuration
- [STARTUP_JSON_VERIFICATION.md](./docs/STARTUP_JSON_VERIFICATION.md) - Verify startup configuration
- [STARTUP_JSON_FIX.md](./docs/STARTUP_JSON_FIX.md) - Fix startup issues
- [HOW_TO_SWITCH_DATABASE.md](./docs/HOW_TO_SWITCH_DATABASE.md) - Switch between databases
### 🛠️ Path Configuration & Fixes
- **[WEBDIR_ISSUE_COMPLETE_FIX.md](./docs/WEBDIR_ISSUE_COMPLETE_FIX.md)** - **Complete guide to fixing WebDir path issues** (NEW)
- **[STARTUP_JSON_WEBDIR_FIX.md](./docs/STARTUP_JSON_WEBDIR_FIX.md)** - **Fix startup.json WebDir configuration** (NEW)
- **[PATH_FIX_GUIDE.md](./docs/PATH_FIX_GUIDE.md)** - **Comprehensive path fix guide** (NEW)
- **[LINUX_PATH_ISSUE_SUMMARY.md](./docs/LINUX_PATH_ISSUE_SUMMARY.md)** - **Linux paths on Windows issue summary** (NEW)
- **[FIX_SYSTEM_XML_PATHS.md](./docs/FIX_SYSTEM_XML_PATHS.md)** - **Fix Linux paths in system.xml** (NEW)
- **[POWERSHELL_SCRIPT_FIXED.md](./docs/POWERSHELL_SCRIPT_FIXED.md)** - **PowerShell utility script fixes** (NEW)
### 🔧 Utility Scripts
- **[FixJellyfinPaths.ps1](./FixJellyfinPaths.ps1)** - **PowerShell script to fix Linux paths in configuration files** (NEW)
- **[FixStartupJsonWebDir.ps1](./FixStartupJsonWebDir.ps1)** - **PowerShell script to fix WebDir paths in startup.json** (NEW)
- **[add_presentationuniquekey_index.sql](./add_presentationuniquekey_index.sql)** - **SQL script to add performance index for episode queries** (NEW)
- **[fix_windows_paths.sql](./fix_windows_paths.sql)** - **SQL script to convert Linux paths to Windows paths** (NEW)
### 🗄️ PostgreSQL Setup & Migration
- **[QUICKSTART_POSTGRESQL.md](./docs/QUICKSTART_POSTGRESQL.md)** - Quick PostgreSQL setup
- **[MULTI_INSTANCE_QUICKSTART.md](./docs/MULTI_INSTANCE_QUICKSTART.md)** - **Quick start for multi-instance deployment** (NEW)
- **[MULTI_INSTANCE_SUPPORT_PLAN.md](./docs/MULTI_INSTANCE_SUPPORT_PLAN.md)** - **Multi-instance deployment architecture** (NEW)
- **[MULTI_INSTANCE_SUPPORT_SUMMARY.md](./docs/MULTI_INSTANCE_SUPPORT_SUMMARY.md)** - **Multi-instance implementation status** (NEW)
- [POSTGRESQL_MIGRATION_COMPLETE.md](./docs/POSTGRESQL_MIGRATION_COMPLETE.md) - Migration guide
- [POSTGRESQL_TROUBLESHOOTING.md](./docs/POSTGRESQL_TROUBLESHOOTING.md) - Troubleshooting guide
- [MERGE_MIGRATIONS_GUIDE.md](./docs/MERGE_MIGRATIONS_GUIDE.md) - Merge pending migrations
- [database/postgres-migration-guide.md](./docs/database/postgres-migration-guide.md) - Detailed migration steps
- [database/postgres-provider-readme.md](./docs/database/postgres-provider-readme.md) - PostgreSQL provider documentation
- [database/jellyfin-database-readme.md](./docs/database/jellyfin-database-readme.md) - Database architecture
### 💾 Backup & Restore
- **[remote-postgresql-backup-support.md](./docs/remote-postgresql-backup-support.md)** - Remote PostgreSQL backups
- [database/postgres-backup-configuration.md](./docs/database/postgres-backup-configuration.md) - Backup configuration guide
- [POSTGRES_BACKUP_IMPLEMENTATION.md](./docs/POSTGRES_BACKUP_IMPLEMENTATION.md) - Backup implementation details
- [POSTGRESQL_BACKUP_ANALYSIS.md](./docs/POSTGRESQL_BACKUP_ANALYSIS.md) - Backup analysis
### ⚡ Performance & Optimization
- **[increase-database-timeout.md](./docs/increase-database-timeout.md)** - Fix query timeouts
- [ADD_INDEXES_GUIDE.md](./docs/ADD_INDEXES_GUIDE.md) - Add performance indexes
- [AUTO_APPLY_INDEXES_COMPLETE.md](./docs/AUTO_APPLY_INDEXES_COMPLETE.md) - Automatic index application
- [ITEMVALUES_INDEXES_ADDED.md](./docs/ITEMVALUES_INDEXES_ADDED.md) - ItemValues optimization
- [MISSING_INDEXES_FIXED.md](./docs/MISSING_INDEXES_FIXED.md) - Index fixes
- [query-grouping-current-status.md](./docs/query-grouping-current-status.md) - Query performance status
- [query-optimization-complete-story.md](./docs/query-optimization-complete-story.md) - Complete optimization guide
- [database-query-optimization.md](./docs/database-query-optimization.md) - Query optimization strategies
### 🔍 Database Diagnostics & Analysis
- **[DIAGNOSTICS_COMPLETE_SUMMARY.md](./docs/DIAGNOSTICS_COMPLETE_SUMMARY.md)** - ⭐ Complete diagnostics overview
- [DATABASE_ANALYSIS_REPORT.md](./docs/DATABASE_ANALYSIS_REPORT.md) - Detailed analysis
- [LATEST_DIAGNOSTICS_ANALYSIS.md](./docs/LATEST_DIAGNOSTICS_ANALYSIS.md) - Latest diagnostics
- [REMOTE_DATABASE_ANALYSIS.md](./docs/REMOTE_DATABASE_ANALYSIS.md) - Remote database analysis
- [REMOTE_ANALYSIS_SUMMARY.md](./docs/REMOTE_ANALYSIS_SUMMARY.md) - Remote analysis summary
- [QUICK_ACTION_PLAN.md](./docs/QUICK_ACTION_PLAN.md) - Performance action plan
- [WEEKLY_TRACKING.md](./docs/WEEKLY_TRACKING.md) - Weekly tracking template
### 🔧 Error Fixes & Troubleshooting
- **[sqlite-migration-filtering-fix.md](./docs/sqlite-migration-filtering-fix.md)** - Fix SQLite migration errors
- **[LIBRARYMONITOR_DISPOSAL_FIX.md](./docs/LIBRARYMONITOR_DISPOSAL_FIX.md)** - **Fix ObjectDisposedException during shutdown** (NEW)
- [syncplay-authorization-error-handling.md](./docs/syncplay-authorization-error-handling.md) - SyncPlay auth errors
- [exception-middleware-authentication-messaging.md](./docs/exception-middleware-authentication-messaging.md) - Authentication error messages
- [database-deadlock-handling.md](./docs/database-deadlock-handling.md) - Handle database deadlocks
- [database-constraint-violation-baseitem-providers.md](./docs/database-constraint-violation-baseitem-providers.md) - Fix constraint violations
- [ef-core-tracking-conflict-fix.md](./docs/ef-core-tracking-conflict-fix.md) - EF Core tracking issues
- [TROUBLESHOOTING_EF_PENDING_CHANGES.md](./docs/TROUBLESHOOTING_EF_PENDING_CHANGES.md) - EF Core pending changes
- [WEBSOCKET_TOKEN_REQUIRED_ERROR.md](./docs/WEBSOCKET_TOKEN_REQUIRED_ERROR.md) - WebSocket errors
### 📦 Installation & Publishing
- **[INSTALLER_QUICK_START.md](./docs/INSTALLER_QUICK_START.md)** - Quick installer guide
- [INSTALLER_GUIDE.md](./docs/INSTALLER_GUIDE.md) - Detailed installer guide
- [CENTRALIZED_LIB_FOLDER.md](./docs/CENTRALIZED_LIB_FOLDER.md) - Centralized build output
- [BUILD_INSTALLER_FIXED.md](./docs/BUILD_INSTALLER_FIXED.md) - Installer build fixes
- [SQL_FILES_PUBLISH_FIX.md](./docs/SQL_FILES_PUBLISH_FIX.md) - SQL files in publish
- [SQL_PUBLISH_ISSUE_RESOLVED.md](./docs/SQL_PUBLISH_ISSUE_RESOLVED.md) - SQL publish resolution
- [QUICK_PUBLISH_REFERENCE.md](./docs/QUICK_PUBLISH_REFERENCE.md) - Publish reference
### 📜 Project Information & Planning
- [PROJECT_COMPLETION.md](./docs/PROJECT_COMPLETION.md) - Project completion status
- [POC_SUMMARY_REPORT.md](./docs/POC_SUMMARY_REPORT.md) - Proof of concept summary
- [IMPLEMENTATION_COMPLETE.md](./docs/IMPLEMENTATION_COMPLETE.md) - Implementation status
- [PR_DESCRIPTION.md](./docs/PR_DESCRIPTION.md) - Pull request description
- [PR_DESCRIPTION_SHORT.md](./docs/PR_DESCRIPTION_SHORT.md) - Short PR description
- [STAKEHOLDER_PRESENTATION.md](./docs/STAKEHOLDER_PRESENTATION.md) - Stakeholder presentation
- [SQLITE_REMOVAL_PLAN.md](./docs/SQLITE_REMOVAL_PLAN.md) - SQLite removal plan
### 🛠️ Developer Resources
- [README_EDITORCONFIG_CHANGES.md](./docs/README_EDITORCONFIG_CHANGES.md) - EditorConfig changes
- [README_GENERATION.md](./docs/README_GENERATION.md) - Documentation generation
- [STARTUP_CONFIG_COMPARISON.md](./docs/STARTUP_CONFIG_COMPARISON.md) - Configuration comparison
- [STARTUP_CONFIG_UPDATE.md](./docs/STARTUP_CONFIG_UPDATE.md) - Configuration updates
- [STARTUP_JSON_MARKER_FIX.md](./docs/STARTUP_JSON_MARKER_FIX.md) - JSON marker fixes
- [STARTUP_JSON_VISUAL_GUIDE.md](./docs/STARTUP_JSON_VISUAL_GUIDE.md) - Visual configuration guide
- [TEMP_DIR_CONFIGURATION_FEATURE.md](./docs/TEMP_DIR_CONFIGURATION_FEATURE.md) - Temp directory configuration
- [VERSION_UPDATE_11.0.0_PREVIEW.md](./docs/VERSION_UPDATE_11.0.0_PREVIEW.md) - .NET 11 upgrade
- [scripts/CONNECT_AND_UPDATE.md](./docs/scripts/CONNECT_AND_UPDATE.md) - Connection and update scripts
### 📂 Additional Documentation
- [fuzz/README.md](./fuzz/README.md) - Fuzz testing documentation
- [wwwroot/README.md](./wwwroot/README.md) - Web assets documentation
- [Jellyfin.Server/Resources/Configuration/README.md](./Jellyfin.Server/Resources/Configuration/README.md) - Configuration resources
[📁 View All Documentation →](./docs/)
---
## 📝 License
GNU General Public License v2.0
Fork of [Jellyfin](https://github.com/jellyfin/jellyfin)
---
## 📞 Support
- 📚 [Documentation](./docs/)
- 🐛 [Report Bug](https://gitea.wpjones.com/wjones/pgsql-jellyfin/issues)
- 💡 [Request Feature](https://gitea.wpjones.com/wjones/pgsql-jellyfin/issues)
---
## ⚡ Quick Reference
```bash
# Build
dotnet build --configuration Release
# Run
cd lib/Release/net11.0 && dotnet jellyfin.dll
# Create installer
.\build-installer.ps1
# Test
dotnet test
```
**Essential Paths:**
- Windows: `C:\ProgramData\jellyfin`
- Linux: `/var/lib/jellyfin`
- macOS: `~/Library/Application Support/jellyfin`
---
**Built with ❤️ for the Jellyfin community**
[Jellyfin](https://jellyfin.org) • [PostgreSQL](https://www.postgresql.org) • [.NET](https://dotnet.microsoft.com)
Reference in New Issue View Git Blame Copy Permalink