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:
```json
{
  "_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:**
```powershell
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:**
```bash
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:**
```bash
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:**
```json
{
  "Paths": {
    "DataDir": "C:/ProgramData/jellyfin",
    "CacheDir": "C:/ProgramData/jellyfin/cache"
  }
}
```

**After editing:**
```json
{
  "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! 🎉