Centralize build output and generate OS-specific startup.json

- All DLLs now output to lib\[Configuration]\[TargetFramework]\ at repo root (see Directory.Build.props) - .gitignore updated to exclude /lib/ - On first run, startup.json is auto-generated with OS-appropriate default paths (Windows, Linux, macOS, or portable) - Removes null/example config; generated config is immediately usable and clearly documented - Extensive new documentation: build output, startup.json logic, visual guides, and code proofs - Publish profile now deletes existing files for clean deploys - No breaking changes: existing startup.json files are preserved - Improves first-run UX, deployment, and cross-platform consistency
2026-02-26 14:21:26 -05:00
parent 5bdb7d53c3
commit 8f860a8ec3
35 changed files with 2218 additions and 46 deletions
@@ -0,0 +1,356 @@
+# Jellyfin Path Configuration Guide
+
+## Overview
+All major paths in Jellyfin are now fully configurable through **three methods**: configuration file, command-line options, or environment variables. This allows you to customize where Jellyfin stores its data, logs, cache, configuration, and temporary files.
+
+## Configuration Methods
+
+Jellyfin supports three ways to configure paths (in priority order):
+
+### 1. Configuration File (NEW!)
+Create a `startup.json` file with your path configurations. See [FILE_BASED_STARTUP_CONFIG.md](FILE_BASED_STARTUP_CONFIG.md) for details.
+
+**Example:**
+```json
+{
+  "Paths": {
+    "DataDir": "/var/lib/jellyfin",
+    "ConfigDir": "/etc/jellyfin",
+    "CacheDir": "/var/cache/jellyfin",
+    "LogDir": "/var/log/jellyfin",
+    "TempDir": "/var/tmp/jellyfin"
+  }
+}
+```
+
+### 2. Command-Line Options
+Pass options when starting Jellyfin.
+
+**Example:**
+```bash
+jellyfin --datadir /var/lib/jellyfin --logdir /var/log/jellyfin
+```
+
+### 3. Environment Variables
+Set environment variables in your shell or systemd service.
+
+**Example:**
+```bash
+export JELLYFIN_DATA_DIR=/var/lib/jellyfin
+export JELLYFIN_LOG_DIR=/var/log/jellyfin
+```
+
+## Priority Order
+
+When a path is configured in multiple places, Jellyfin uses this priority (highest to lowest):
+
+1. **Command-line options** (highest priority)
+2. **Environment variables**
+3. **Configuration file** (`startup.json`)
+4. **Default values** (lowest priority)
+
+This allows you to:
+- Set defaults in a configuration file
+- Override system-wide with environment variables
+- Override temporarily with command-line options
+
+## Available Path Configurations
+
+### 1. Program Data Directory (Database Files)
+**Purpose**: Main directory for database files and application data
+
+- **Configuration File**: `Paths:DataDir` in `startup.json`
+- **Command Line**: `-d, --datadir <path>`
+- **Environment Variable**: `JELLYFIN_DATA_DIR`
+- **Default**: 
+  - Windows: `%LocalAppData%\jellyfin`
+  - Linux/Unix: `$XDG_DATA_HOME/jellyfin` or `~/.local/share/jellyfin`
+  - macOS: `~/Library/Application Support/jellyfin`
+
+**Example**:
+```bash
+# Configuration file (startup.json)
+{
+  "Paths": {
+    "DataDir": "/var/lib/jellyfin"
+  }
+}
+
+# Command line
+jellyfin --datadir /var/lib/jellyfin
+
+# Environment variable
+export JELLYFIN_DATA_DIR=/var/lib/jellyfin
+```
+
+### 2. Configuration Directory
+**Purpose**: User settings, pictures, and configuration files
+
+- **Configuration File**: `Paths:ConfigDir` in `startup.json`
+- **Command Line**: `-c, --configdir <path>`
+- **Environment Variable**: `JELLYFIN_CONFIG_DIR`
+- **Default**: 
+  - Windows/macOS: `{datadir}/config`
+  - Linux/Unix: `$XDG_CONFIG_HOME/jellyfin` or `~/.config/jellyfin`
+
+**Example**:
+```bash
+# Configuration file
+{
+  "Paths": {
+    "ConfigDir": "/etc/jellyfin"
+  }
+}
+
+# Command line
+jellyfin --configdir /etc/jellyfin
+
+# Environment variable
+export JELLYFIN_CONFIG_DIR=/etc/jellyfin
+```
+
+### 3. Cache Directory
+**Purpose**: Image cache, metadata cache, and other temporary cached data
+
+- **Configuration File**: `Paths:CacheDir` in `startup.json`
+- **Command Line**: `-C, --cachedir <path>`
+- **Environment Variable**: `JELLYFIN_CACHE_DIR`
+- **Default**: 
+  - Windows/macOS: `{datadir}/cache`
+  - Linux/Unix: `$XDG_CACHE_HOME/jellyfin` or `~/.cache/jellyfin`
+
+**Example**:
+```bash
+# Configuration file
+{
+  "Paths": {
+    "CacheDir": "/var/cache/jellyfin"
+  }
+}
+
+# Command line
+jellyfin --cachedir /var/cache/jellyfin
+
+# Environment variable
+export JELLYFIN_CACHE_DIR=/var/cache/jellyfin
+```
+
+### 4. Log Directory
+**Purpose**: Application log files
+
+- **Configuration File**: `Paths:LogDir` in `startup.json`
+- **Command Line**: `-l, --logdir <path>`
+- **Environment Variable**: `JELLYFIN_LOG_DIR`
+- **Default**: `{datadir}/log`
+
+**Example**:
+```bash
+# Configuration file
+{
+  "Paths": {
+    "LogDir": "/var/log/jellyfin"
+  }
+}
+
+# Command line
+jellyfin --logdir /var/log/jellyfin
+
+# Environment variable
+export JELLYFIN_LOG_DIR=/var/log/jellyfin
+```
+
+### 5. Temp Directory ⭐ NEW
+**Purpose**: Temporary files created during transcoding and other operations
+
+- **Configuration File**: `Paths:TempDir` in `startup.json`
+- **Command Line**: `-t, --tempdir <path>`
+- **Environment Variable**: `JELLYFIN_TEMP_DIR`
+- **Default**: `{system_temp}/jellyfin` (e.g., `/tmp/jellyfin` on Linux)
+
+**Example**:
+```bash
+# Configuration file
+{
+  "Paths": {
+    "TempDir": "/var/tmp/jellyfin"
+  }
+}
+
+# Command line
+jellyfin --tempdir /var/tmp/jellyfin
+
+# Environment variable
+export JELLYFIN_TEMP_DIR=/var/tmp/jellyfin
+```
+
+### 6. Web Client Directory
+**Purpose**: Location of the Jellyfin web client files
+
+- **Configuration File**: `Paths:WebDir` in `startup.json`
+- **Command Line**: `-w, --webdir <path>`
+- **Environment Variable**: `JELLYFIN_WEB_DIR`
+- **Default**: 
+  1. Searches for `wwwroot` folder in solution root (development)
+  2. Falls back to `{appdir}/jellyfin-web`
+
+**Example**:
+```bash
+# Configuration file
+{
+  "Paths": {
+    "WebDir": "/usr/share/jellyfin/web"
+  }
+}
+
+# Command line
+jellyfin --webdir /usr/share/jellyfin/web
+
+# Environment variable
+export JELLYFIN_WEB_DIR=/usr/share/jellyfin/web
+```
+
+## Usage Examples
+
+### Using Command Line Options
+```bash
+# Windows
+jellyfin.exe --datadir "C:\ProgramData\Jellyfin" --logdir "C:\Logs\Jellyfin" --tempdir "D:\Temp\Jellyfin"
+
+# Linux
+jellyfin --datadir /var/lib/jellyfin --logdir /var/log/jellyfin --tempdir /var/tmp/jellyfin --cachedir /var/cache/jellyfin
+```
+
+### Using Environment Variables
+```bash
+# Linux/macOS - Add to ~/.bashrc or /etc/environment
+export JELLYFIN_DATA_DIR=/var/lib/jellyfin
+export JELLYFIN_CONFIG_DIR=/etc/jellyfin
+export JELLYFIN_CACHE_DIR=/var/cache/jellyfin
+export JELLYFIN_LOG_DIR=/var/log/jellyfin
+export JELLYFIN_TEMP_DIR=/var/tmp/jellyfin
+export JELLYFIN_WEB_DIR=/usr/share/jellyfin/web
+
+# Windows - Set in PowerShell or System Properties
+$env:JELLYFIN_DATA_DIR="C:\ProgramData\Jellyfin"
+$env:JELLYFIN_LOG_DIR="C:\Logs\Jellyfin"
+$env:JELLYFIN_TEMP_DIR="D:\Temp\Jellyfin"
+```
+
+### Systemd Service (Linux)
+Create or edit `/etc/systemd/system/jellyfin.service`:
+
+```ini
+[Unit]
+Description=Jellyfin Media Server
+After=network-online.target
+
+[Service]
+Type=simple
+User=jellyfin
+Group=jellyfin
+Environment="JELLYFIN_DATA_DIR=/var/lib/jellyfin"
+Environment="JELLYFIN_CONFIG_DIR=/etc/jellyfin"
+Environment="JELLYFIN_CACHE_DIR=/var/cache/jellyfin"
+Environment="JELLYFIN_LOG_DIR=/var/log/jellyfin"
+Environment="JELLYFIN_TEMP_DIR=/var/tmp/jellyfin"
+Environment="JELLYFIN_WEB_DIR=/usr/share/jellyfin/web"
+ExecStart=/usr/bin/jellyfin
+
+[Install]
+WantedBy=multi-user.target
+```
+
+## Priority Order
+
+When determining which path to use, Jellyfin follows this priority:
+
+1. **Command-line option** (highest priority)
+2. **Environment variable**
+3. **Default value** (lowest priority)
+
+This allows you to:
+- Set system-wide defaults via environment variables
+- Override on a per-run basis with command-line options
+- Fall back to sensible defaults if nothing is specified
+
+## Directory Permissions
+
+Ensure the user running Jellyfin has appropriate permissions:
+
+```bash
+# Linux example - create directories and set permissions
+sudo mkdir -p /var/lib/jellyfin /etc/jellyfin /var/cache/jellyfin /var/log/jellyfin /var/tmp/jellyfin
+sudo chown -R jellyfin:jellyfin /var/lib/jellyfin /etc/jellyfin /var/cache/jellyfin /var/log/jellyfin /var/tmp/jellyfin
+sudo chmod 755 /var/lib/jellyfin /etc/jellyfin /var/cache/jellyfin /var/log/jellyfin /var/tmp/jellyfin
+```
+
+## Benefits
+
+### Performance
+- Place temp directory on fast storage (SSD/NVMe) for transcoding performance
+- Put cache on separate disk to reduce I/O contention
+- Use different mount points for logs vs data
+
+### Storage Management
+- Separate data across different partitions/disks
+- Use network storage for backups while keeping temp on local fast storage
+- Easier to manage disk space quotas
+
+### Security
+- Follow OS security best practices (e.g., `/var` hierarchy on Linux)
+- Set appropriate permissions per directory type
+- Separate user data from system configuration
+
+### Containerization
+- Map volumes to specific paths
+- Follow container best practices (ephemeral temp, persistent data)
+- Easier Docker/Podman volume mounting
+
+### Backup & Maintenance
+- Backup only important directories (data, config) and skip cache/temp
+- Easier to exclude temporary files from backups
+- Simplified cleanup of cache and temp directories
+
+## Docker Example
+
+```yaml
+version: '3.8'
+services:
+  jellyfin:
+    image: jellyfin/jellyfin:latest
+    environment:
+      - JELLYFIN_DATA_DIR=/data
+      - JELLYFIN_CONFIG_DIR=/config
+      - JELLYFIN_CACHE_DIR=/cache
+      - JELLYFIN_LOG_DIR=/log
+      - JELLYFIN_TEMP_DIR=/temp
+    volumes:
+      - /host/jellyfin/data:/data
+      - /host/jellyfin/config:/config
+      - /host/jellyfin/cache:/cache
+      - /host/jellyfin/log:/log
+      - /fast-storage/jellyfin/temp:/temp
+    ports:
+      - "8096:8096"
+```
+
+## Verification
+
+After starting Jellyfin, check the logs to verify paths are set correctly:
+
+```
+[INF] Program data path: /var/lib/jellyfin
+[INF] Config directory path: /etc/jellyfin
+[INF] Cache path: /var/cache/jellyfin
+[INF] Log directory path: /var/log/jellyfin
+[INF] Temp directory path: /var/tmp/jellyfin
+[INF] Web resources path: /usr/share/jellyfin/web
+```
+
+## Notes
+
+- All paths are created automatically if they don't exist (permissions allowing)
+- Paths are normalized to absolute paths internally
+- Relative paths are resolved from the current working directory
+- Changes require a restart to take effect
+- Command-line help: `jellyfin --help`