pgsql-jellyfin/docs/PATH_CONFIGURATION_GUIDE.md

# 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`