pgsql-jellyfin/docs/OS_SPECIFIC_STARTUP_CONFIG.md

# OS-Specific startup.json Generation

## Overview
The `startup.json` file is now automatically generated with **OS-specific default paths** instead of null values.

---

## Generated Content by Operating System

### Windows Example
When Jellyfin starts on Windows and no `startup.json` exists, it creates:

```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/<user>/AppData/Local/Temp/jellyfin",
    "WebDir": "C:/ProgramData/jellyfin/web"
  }
}
```

### Linux Example
When Jellyfin starts on Linux and no `startup.json` exists, it creates:

```json
{
  "_comment": "Jellyfin Startup Configuration - Linux defaults - following Filesystem Hierarchy Standard (FHS)",
  "_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": "/var/lib/jellyfin",
    "ConfigDir": "/etc/jellyfin",
    "CacheDir": "/var/cache/jellyfin",
    "LogDir": "/var/log/jellyfin",
    "TempDir": "/var/tmp/jellyfin",
    "WebDir": "/usr/share/jellyfin/web"
  }
}
```

### macOS Example
When Jellyfin starts on macOS and no `startup.json` exists, it creates:

```json
{
  "_comment": "Jellyfin Startup Configuration - macOS defaults - using user Library paths",
  "_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": "~/Library/Application Support/jellyfin",
    "ConfigDir": "~/Library/Application Support/jellyfin/config",
    "CacheDir": "~/Library/Caches/jellyfin",
    "LogDir": "~/Library/Logs/jellyfin",
    "TempDir": "/tmp/jellyfin",
    "WebDir": "~/Library/Application Support/jellyfin/web"
  }
}
```

### Portable/Unknown OS Example
When Jellyfin starts on an unknown OS and no `startup.json` exists, it creates:

```json
{
  "_comment": "Jellyfin Startup Configuration - Portable defaults - using relative paths",
  "_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": "./data",
    "ConfigDir": "./config",
    "CacheDir": "./cache",
    "LogDir": "./logs",
    "TempDir": "./temp",
    "WebDir": "./web"
  }
}
```

---

## Platform Standards Followed

### Windows
- **Standard Location:** `C:/ProgramData/jellyfin`
- **Rationale:** ProgramData is the Windows standard for application data shared across all users
- **Permissions:** Requires administrator rights for initial setup

### Linux  
- **Standard:** Filesystem Hierarchy Standard (FHS)
- **Rationale:** Follows Linux best practices for system-wide installations
- **Paths:**
  - `/var/lib/jellyfin` - Application data
  - `/etc/jellyfin` - Configuration files
  - `/var/cache/jellyfin` - Cache files
  - `/var/log/jellyfin` - Log files
  - `/var/tmp/jellyfin` - Temporary files
  - `/usr/share/jellyfin/web` - Web UI assets

### macOS
- **Standard Location:** User's Library folder
- **Rationale:** Follows Apple's guidelines for user-specific applications
- **Paths follow:** macOS file system conventions

### Portable
- **Standard:** Relative paths
- **Rationale:** For USB/portable installations
- **Benefit:** No system-wide installation required

---

## Behavior

### When `startup.json` Doesn't Exist
1. Jellyfin detects no configuration file
2. Calls `CreateDefaultStartupConfiguration()`
3. Detects current operating system
4. Generates appropriate default paths
5. Creates `startup.json` in current directory
6. Displays message to console
7. Uses these paths for startup

### When `startup.json` Exists
- Uses existing configuration
- No automatic generation
- Respects user customizations

---

## Console Output

### On First Run (Windows)
```
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.
```

### On First Run (Linux)
```
Created default startup configuration at: /opt/jellyfin/startup.json
Using Linux defaults - following Filesystem Hierarchy Standard (FHS)
You can customize this file to set different paths for Jellyfin.
```

---

## Priority Order

Jellyfin resolves paths in this priority order:

1. **Command-line arguments** (Highest)
   ```bash
   jellyfin --datadir /custom/path
   ```

2. **Environment variables**
   ```bash
   export JELLYFIN_DATA_DIR=/custom/path
   ```

3. **startup.json file**
   ```json
   { "Paths": { "DataDir": "/custom/path" } }
   ```

4. **Built-in OS defaults** (Lowest)
   - Determined by `CreateApplicationPaths()` method

---

## Customization Examples

### Change Just the Data Directory
```json
{
  "Paths": {
    "DataDir": "/mnt/storage/jellyfin",
    "ConfigDir": "/etc/jellyfin",
    "CacheDir": "/var/cache/jellyfin",
    "LogDir": "/var/log/jellyfin",
    "TempDir": "/var/tmp/jellyfin",
    "WebDir": "/usr/share/jellyfin/web"
  }
}
```

### Use All Custom Paths
```json
{
  "Paths": {
    "DataDir": "D:/Media/Jellyfin/Data",
    "ConfigDir": "D:/Media/Jellyfin/Config",
    "CacheDir": "E:/Cache/Jellyfin",
    "LogDir": "D:/Logs/Jellyfin",
    "TempDir": "F:/Temp/Jellyfin",
    "WebDir": "C:/Program Files/Jellyfin/Web"
  }
}
```

### Portable Installation
```json
{
  "Paths": {
    "DataDir": "./data",
    "ConfigDir": "./config",
    "CacheDir": "./cache",
    "LogDir": "./logs",
    "TempDir": "./temp",
    "WebDir": "./web"
  }
}
```

---

## Benefits

✅ **No manual configuration needed** - Works out of the box  
✅ **OS-appropriate defaults** - Follows platform conventions  
✅ **Easy to customize** - Edit one JSON file  
✅ **Clear documentation** - Comments explain what to change  
✅ **Cross-platform** - Same behavior on all platforms  
✅ **Backward compatible** - Existing startup.json files still work  

---

## Testing

### Test on Windows
1. Delete existing `startup.json`
2. Run Jellyfin
3. Check that `startup.json` was created with Windows paths
4. Verify Jellyfin uses `C:/ProgramData/jellyfin`

### Test on Linux
1. Delete existing `startup.json`
2. Run Jellyfin
3. Check that `startup.json` was created with Linux FHS paths
4. Verify Jellyfin uses `/var/lib/jellyfin`, `/etc/jellyfin`, etc.

### Test Customization
1. Create `startup.json` with custom paths
2. Run Jellyfin
3. Verify it uses your custom paths
4. No new file should be generated

---

## Related Files

- **Code:** `Jellyfin.Server/Helpers/StartupHelpers.cs`
- **Method:** `CreateDefaultStartupConfiguration()`
- **Templates:** 
  - `Jellyfin.Server/Resources/Configuration/startup.linux.json`
  - `Jellyfin.Server/Resources/Configuration/startup.windows.json`
  - `Jellyfin.Server/Resources/Configuration/startup.default.json`

---

## Troubleshooting

### File Not Created
**Issue:** startup.json not being created  
**Solution:** Check write permissions in current directory

### Wrong OS Detected
**Issue:** Getting incorrect OS-specific paths  
**Solution:** Check `OperatingSystem.IsWindows()`, etc. detection

### Want Different Defaults
**Issue:** Don't like the auto-generated defaults  
**Solution:** Just edit the `startup.json` file - it won't be regenerated

---

## Future Enhancements

- 📋 Add interactive setup wizard
- 📋 Add validation for path accessibility
- 📋 Add migration tool for moving data between paths
- 📋 Add path recommendations based on available storage

---

**Status:** ✅ Production Ready  
**Build:** ✅ Successful  
**Testing:** Ready for user testing