pgsql-jellyfin/docs/STARTUP_JSON_VISUAL_GUIDE.md

Visual Guide: startup.json Auto-Generation

Step-by-Step Process

Step 1: User Starts Jellyfin (No startup.json exists)

$ jellyfin

Step 2: System Detects Operating System

┌──────────────────────────┐
│   Detect OS Platform     │
└────────┬─────────────────┘
         │
    ┌────▼────┐
    │ Windows?│──Yes──► Use C:/ProgramData/jellyfin
    └────┬────┘
         │No
    ┌────▼────┐
    │ Linux?  │──Yes──► Use /var/lib, /etc, /var/log
    └────┬────┘
         │No
    ┌────▼────┐
    │ macOS?  │──Yes──► Use ~/Library paths
    └────┬────┘
         │No
         ▼
   Use Relative Paths (./data, ./config)

Step 3: Generate startup.json

On Your Windows System:

{
  "_comment": "Jellyfin Startup Configuration - Windows defaults - using C:/ProgramData/jellyfin",
  "_note": "These paths will be used unless overridden by environment variables or command-line arguments",
  "_priority": "Command-line args > Environment variables > This file > Built-in defaults",
  "_examples": "See startup.linux.json or startup.windows.json in Resources/Configuration for other OS examples",
  "Paths": {
    "DataDir": "C:/ProgramData/jellyfin",
    "ConfigDir": "C:/ProgramData/jellyfin",
    "CacheDir": "C:/ProgramData/jellyfin/cache",
    "LogDir": "C:/ProgramData/jellyfin/log",
    "TempDir": "C:/Users/YourUser/AppData/Local/Temp/jellyfin",
    "WebDir": "C:/ProgramData/jellyfin/web"
  }
}

Step 4: Console Output

Created default startup configuration at: E:\Jellyfin\startup.json
Using Windows defaults - using C:/ProgramData/jellyfin
You can customize this file to set different paths for Jellyfin.

Step 5: Jellyfin Uses These Paths

[INF] Starting Jellyfin
[INF] Data directory: C:/ProgramData/jellyfin
[INF] Config directory: C:/ProgramData/jellyfin
[INF] Cache directory: C:/ProgramData/jellyfin/cache
[INF] Log directory: C:/ProgramData/jellyfin/log

---

Complete Comparison

🔴 OLD WAY (Before This Change)

User starts Jellyfin
    ↓
Creates startup.json with:
    {
      "DataDir": null,
      "ConfigDir": null,
      ...
    }
    ↓
❌ User confused: "What should I put here?"
    ↓
User searches documentation
    ↓
User manually edits file
    ↓
User restarts Jellyfin
    ↓
✅ Finally works

Time to get working: 10-30 minutes (depending on documentation search)

🟢 NEW WAY (After This Change)

User starts Jellyfin
    ↓
Creates startup.json with:
    {
      "DataDir": "C:/ProgramData/jellyfin",
      "ConfigDir": "C:/ProgramData/jellyfin",
      ...
    }
    ↓
✅ Immediately works with sensible defaults!
    ↓
(Optional: User can customize if desired)

Time to get working: Instant!

---

Real-World Examples

Example 1: First-Time Windows User

User Action:

cd C:\Jellyfin
.\jellyfin.exe

What Happens:

1. Jellyfin sees no startup.json
2. Detects Windows OS
3. Creates startup.json with C:/ProgramData/jellyfin paths
4. Starts using those paths immediately
5. ✅ Works out of the box!

Generated File Location: C:\Jellyfin\startup.json

Example 2: Linux Server Installation

User Action:

cd /opt/jellyfin
./jellyfin

What Happens:

1. Jellyfin sees no startup.json
2. Detects Linux OS
3. Creates startup.json with FHS-compliant paths
4. Starts using /var/lib/jellyfin, /etc/jellyfin, etc.
5. ✅ Follows Linux best practices automatically!

Generated File Location: /opt/jellyfin/startup.json

Example 3: Portable USB Installation

User Action:

cd /media/usb/jellyfin
./jellyfin

What Happens:

1. Jellyfin sees no startup.json
2. Detects unknown/portable scenario
3. Creates startup.json with relative paths
4. Starts using ./data, ./config, etc.
5. ✅ Self-contained and portable!

Generated File Location: /media/usb/jellyfin/startup.json

---

Customization Still Easy

If you want different paths, just edit the file:

Before editing:

{
  "Paths": {
    "DataDir": "C:/ProgramData/jellyfin",
    "CacheDir": "C:/ProgramData/jellyfin/cache"
  }
}

After editing:

{
  "Paths": {
    "DataDir": "D:/Media/Jellyfin/Data",
    "CacheDir": "E:/FastSSD/Cache/Jellyfin"
  }
}

Then restart Jellyfin - it will use your custom paths!

---

File Structure Visualization

Windows

C:/ProgramData/jellyfin/
├── data/          (DataDir)
├── cache/         (CacheDir)
├── log/           (LogDir)
├── config/        (ConfigDir - if not same as DataDir)
└── web/           (WebDir)

Linux

System Directories:
├── /var/lib/jellyfin/      (DataDir)
├── /etc/jellyfin/          (ConfigDir)
├── /var/cache/jellyfin/    (CacheDir)
├── /var/log/jellyfin/      (LogDir)
├── /var/tmp/jellyfin/      (TempDir)
└── /usr/share/jellyfin/    (WebDir)

macOS

~/Library/
├── Application Support/
│   └── jellyfin/          (DataDir, ConfigDir, WebDir)
├── Caches/
│   └── jellyfin/          (CacheDir)
└── Logs/
    └── jellyfin/          (LogDir)

---

Summary

What Changed

• Code: One method in StartupHelpers.cs
• Behavior: Generates OS-specific defaults instead of nulls
• Impact: Massive improvement in first-run experience

User Benefits

• ✅ No configuration needed
• ✅ Works immediately
• ✅ Follows platform conventions
• ✅ Clear documentation
• ✅ Still fully customizable

Developer Benefits

• ✅ Fewer support questions
• ✅ Better user onboarding
• ✅ Platform best practices enforced
• ✅ Reduced documentation needs

---

Result: Jellyfin now "just works" on first install! 🎉