pgsql-jellyfin/docs/PUBLISHING_PROFILES_GUIDE.md

Publishing Profiles for Multi-Instance Jellyfin

Overview

Three publishing profiles have been created for deploying your multi-instance PostgreSQL-enabled Jellyfin:

1. MultiInstance-Win-x64 - Self-contained Windows deployment
2. MultiInstance-Linux-x64 - Self-contained Linux deployment
3. MultiInstance-FrameworkDependent - Smaller deployment requiring .NET 11 runtime

Publishing Profiles

1. MultiInstance-Win-x64 (Recommended for Windows)

Best for: Windows production deployments

Features:

• ✅ Self-contained (includes .NET 11 runtime)
• ✅ Windows x64 optimized
• ✅ ReadyToRun compilation (faster startup)
• ✅ Includes SQL scripts for multi-instance setup
• ✅ Includes documentation

Output: Jellyfin.Server\bin\Publish\MultiInstance-Win-x64\

Usage:

# Command line
dotnet publish Jellyfin.Server\Jellyfin.Server.csproj -p:PublishProfile=MultiInstance-Win-x64

# Or from Visual Studio:
# Right-click Jellyfin.Server project → Publish → MultiInstance-Win-x64

2. MultiInstance-Linux-x64 (Recommended for Linux)

Best for: Linux production deployments

Features:

• ✅ Self-contained (includes .NET 11 runtime)
• ✅ Linux x64 optimized
• ✅ ReadyToRun compilation (faster startup)
• ✅ Includes SQL scripts and documentation

Output: Jellyfin.Server\bin\Publish\MultiInstance-Linux-x64\

Usage:

# Command line
dotnet publish Jellyfin.Server\Jellyfin.Server.csproj -p:PublishProfile=MultiInstance-Linux-x64

# On Linux:
chmod +x ./jellyfin
./jellyfin

3. MultiInstance-FrameworkDependent

Best for: Environments with .NET 11 runtime pre-installed

Features:

• ✅ Smaller deployment size (~100MB vs ~150MB for self-contained)
• ✅ Requires .NET 11 runtime on target system
• ✅ Faster deployment/transfer
• ✅ Centralized runtime management

Output: Jellyfin.Server\bin\Publish\MultiInstance-FrameworkDependent\

Prerequisites: Target system must have .NET 11 runtime installed:

# Check if .NET 11 is installed
dotnet --list-runtimes | Select-String "Microsoft.NETCore.App 11"

# Install if missing
# Download from: https://dotnet.microsoft.com/download/dotnet/11.0

Usage:

dotnet publish Jellyfin.Server\Jellyfin.Server.csproj -p:PublishProfile=MultiInstance-FrameworkDependent

What Gets Published

All profiles include:

Core Application

• ✅ jellyfin.exe (Windows) or jellyfin (Linux)
• ✅ All .NET assemblies and dependencies
• ✅ Npgsql provider for PostgreSQL
• ✅ Multi-instance clustering code (Phases 1-6)

Configuration Files

• ✅ startup.json.windows - Windows configuration template
• ✅ startup.json.linux - Linux configuration template
• ✅ appsettings.json - Application settings

SQL Scripts

• ✅ sql/add_multi_instance_support.sql - Complete multi-instance setup
• ✅ All database migration scripts

Documentation

• ✅ docs/MULTI_INSTANCE_COMPLETE.md - Complete implementation guide
• ✅ docs/PHASE5_PRIMARY_ELECTION_COMPLETE.md - Primary election details
• ✅ docs/PHASE6_FILESYSTEM_COORDINATION_COMPLETE.md - File system coordination
• ✅ docs/POSTGRESQL_CONNECTION_TROUBLESHOOTING.md - Connection troubleshooting

Web Client

• ✅ wwwroot/ - Jellyfin web interface files

Deployment Workflow

Step 1: Choose Your Profile

# For Windows production server
$profile = "MultiInstance-Win-x64"

# For Linux production server
$profile = "MultiInstance-Linux-x64"

# For server with .NET 11 runtime installed
$profile = "MultiInstance-FrameworkDependent"

Step 2: Publish

# From project root
cd D:\Projects\pgsql-jellyfin

# Clean previous builds
dotnet clean Jellyfin.Server\Jellyfin.Server.csproj --configuration Release

# Publish
dotnet publish Jellyfin.Server\Jellyfin.Server.csproj `
    -p:PublishProfile=$profile `
    --configuration Release

Step 3: Verify Output

# Check publish directory
$publishDir = "Jellyfin.Server\bin\Publish\$profile"
Get-ChildItem $publishDir

# Verify critical files exist
Test-Path "$publishDir\jellyfin.exe"  # Windows
Test-Path "$publishDir\sql\add_multi_instance_support.sql"
Test-Path "$publishDir\docs\MULTI_INSTANCE_COMPLETE.md"

Step 4: Deploy to Server

Option A: Copy to Local Path

$deployPath = "C:\Program Files\Jellyfin-MultiInstance"
Copy-Item -Path "$publishDir\*" -Destination $deployPath -Recurse -Force

Option B: Copy to Network Share

$networkPath = "\\server\share\Jellyfin"
Copy-Item -Path "$publishDir\*" -Destination $networkPath -Recurse -Force

Option C: Package for Transfer

# Create ZIP archive
$version = "multi-instance-$(Get-Date -Format 'yyyyMMdd')"
Compress-Archive -Path "$publishDir\*" `
    -DestinationPath "Jellyfin-$version.zip" `
    -Force

Step 5: Configure on Target Server

1. Create database.xml in config directory:

<?xml version="1.0" encoding="utf-8"?>
<DatabaseConfigurationOptions>
  <DatabaseType>Jellyfin-PostgreSQL</DatabaseType>
  <CustomProviderOptions>
    <ConnectionString>Host=YOUR_PG_SERVER;Port=5432;Database=jellyfin;Username=jellyfin;Password=YOUR_PASSWORD</ConnectionString>
  </CustomProviderOptions>
</DatabaseConfigurationOptions>

2. Run multi-instance SQL (first deployment only):

psql -h YOUR_PG_SERVER -U jellyfin -d jellyfin -f sql\add_multi_instance_support.sql

3. Start Jellyfin:

# Windows
.\jellyfin.exe

# Linux
./jellyfin

Visual Studio Publishing

Method 1: Using Solution Explorer

1. Right-click Jellyfin.Server project
2. Click Publish
3. Select one of the multi-instance profiles:
   • MultiInstance-Win-x64
   • MultiInstance-Linux-x64
   • MultiInstance-FrameworkDependent
4. Click Publish

Method 2: Using Publish Dialog

1. Build → Publish Jellyfin.Server
2. Choose Folder target
3. Select existing profile from dropdown
4. Click Publish

Continuous Deployment

PowerShell Script

# PublishAndDeploy.ps1
param(
    [string]$Profile = "MultiInstance-Win-x64",
    [string]$DeployPath = "C:\Program Files\Jellyfin-MultiInstance",
    [switch]$SkipDeploy
)

# Publish
Write-Host "Publishing with profile: $Profile" -ForegroundColor Cyan
dotnet publish Jellyfin.Server\Jellyfin.Server.csproj `
    -p:PublishProfile=$Profile `
    --configuration Release

if ($LASTEXITCODE -ne 0) {
    Write-Error "Publish failed!"
    exit 1
}

$publishDir = "Jellyfin.Server\bin\Publish\$Profile"

# Verify
Write-Host "Verifying publish output..." -ForegroundColor Cyan
if (-not (Test-Path "$publishDir\jellyfin.exe")) {
    Write-Error "jellyfin.exe not found in publish output!"
    exit 1
}

# Deploy
if (-not $SkipDeploy) {
    Write-Host "Deploying to: $DeployPath" -ForegroundColor Cyan
    
    # Stop existing service if running
    Get-Process -Name "jellyfin" -ErrorAction SilentlyContinue | Stop-Process -Force
    
    # Copy files
    Copy-Item -Path "$publishDir\*" -Destination $DeployPath -Recurse -Force
    
    Write-Host "Deployment complete!" -ForegroundColor Green
} else {
    Write-Host "Skipping deployment (use -SkipDeploy:`$false to deploy)" -ForegroundColor Yellow
}

Write-Host "Publish directory: $publishDir" -ForegroundColor Green

Usage:

# Publish and deploy to default location
.\PublishAndDeploy.ps1

# Publish for Linux (no deployment)
.\PublishAndDeploy.ps1 -Profile MultiInstance-Linux-x64 -SkipDeploy

# Publish and deploy to custom location
.\PublishAndDeploy.ps1 -Profile MultiInstance-Win-x64 -DeployPath "D:\Jellyfin"

Deployment Sizes

Profile	Approximate Size	.NET Runtime	Startup Speed
Win-x64 (Self-Contained)	~150MB	✅ Included	Fast (ReadyToRun)
Linux-x64 (Self-Contained)	~150MB	✅ Included	Fast (ReadyToRun)
Framework-Dependent	~100MB	❌ Required on target	Normal

Multi-Instance Deployment

Scenario: 2 Instances on Same Server

Instance 1:

# Deploy to first location
$instance1 = "C:\Jellyfin-Instance1"
Copy-Item -Path "Jellyfin.Server\bin\Publish\MultiInstance-Win-x64\*" `
    -Destination $instance1 -Recurse -Force

# Create config with custom port
# startup.json → port: 8096
# database.xml → Host=192.168.129.248;Database=jellyfin

Instance 2:

# Deploy to second location
$instance2 = "C:\Jellyfin-Instance2"
Copy-Item -Path "Jellyfin.Server\bin\Publish\MultiInstance-Win-x64\*" `
    -Destination $instance2 -Recurse -Force

# Create config with different port
# startup.json → port: 8097
# database.xml → SAME PostgreSQL connection (192.168.129.248)

Both instances will:

• ✅ Connect to the same PostgreSQL database
• ✅ Register as separate instances
• ✅ Coordinate via distributed locks
• ✅ Share cache invalidations
• ✅ Elect primary for scheduled tasks

Troubleshooting

Publish Fails

Check .NET SDK version:

dotnet --version
# Should be 11.x or newer

Clean and retry:

dotnet clean --configuration Release
dotnet publish -p:PublishProfile=MultiInstance-Win-x64

Missing SQL Scripts in Output

The profiles include explicit <ItemGroup> entries to copy SQL files. Verify they exist:

Get-ChildItem -Path "sql\*.sql" -Recurse

Published App Won't Start

Check database.xml location:

# Should be in config directory specified by startup.json
Get-Content "C:\Program Files\Jellyfin-MultiInstance\startup.json" | ConvertFrom-Json | Select-Object -ExpandProperty Paths

Test PostgreSQL connection:

Test-NetConnection -ComputerName 192.168.129.248 -Port 5432

Related Documentation

• 📄 docs/MULTI_INSTANCE_COMPLETE.md - Complete multi-instance overview
• 📄 docs/CONFIGURATION_LOADING_FIX.md - How configuration loading works
• 📄 docs/POSTGRESQL_CONNECTION_TROUBLESHOOTING.md - Connection issues

Summary

✅ Created 3 publishing profiles:

• MultiInstance-Win-x64.pubxml - Windows self-contained
• MultiInstance-Linux-x64.pubxml - Linux self-contained
• MultiInstance-FrameworkDependent.pubxml - Smaller, requires runtime

✅ All profiles include:

• Multi-instance code (all 6 phases)
• SQL setup scripts
• Configuration templates
• Documentation

✅ Ready to use:

dotnet publish -p:PublishProfile=MultiInstance-Win-x64

---

Status: ✅ Publishing profiles ready
Next: Publish and deploy to your servers!