Add file-based startup config & temp dir option
Added support for configuring all major Jellyfin paths (data, config, cache, log, temp, web) via a `startup.json` file, with priority after CLI and environment variables. Introduced a new `TempDir` option, configurable through CLI, env var, or config file, with backward-compatible defaults. Refactored path resolution logic to integrate file-based config and ensure directory creation. Updated constructors and CLI options to support temp directory. Improved EF Core migration error handling and logging. Added comprehensive documentation and example config files. All changes are backward compatible.
This commit is contained in:
@@ -0,0 +1,389 @@
|
||||
# File-Based Startup Configuration
|
||||
|
||||
## Overview
|
||||
Jellyfin now supports file-based configuration for all startup paths in addition to command-line options and environment variables. This provides a persistent, portable way to configure your Jellyfin installation.
|
||||
|
||||
## Configuration Priority
|
||||
|
||||
When determining which path to use, Jellyfin follows this priority (highest to lowest):
|
||||
|
||||
1. **Command-line options** (e.g., `--datadir`)
|
||||
2. **Environment variables** (e.g., `JELLYFIN_DATA_DIR`)
|
||||
3. **Configuration file** (`startup.json`)
|
||||
4. **Default values**
|
||||
|
||||
This allows you to set defaults in a file, override them with environment variables for different environments, and temporarily override with command-line options for testing.
|
||||
|
||||
## Configuration File Location
|
||||
|
||||
The `startup.json` file is searched in the following locations (in order):
|
||||
|
||||
1. **Current working directory**: `./startup.json`
|
||||
2. **Application directory**: `{AppDir}/startup.json`
|
||||
3. **Config subdirectory**: `{AppDir}/config/startup.json`
|
||||
|
||||
The first file found will be used.
|
||||
|
||||
## File Format
|
||||
|
||||
Create a file named `startup.json` with the following structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Supported Properties
|
||||
|
||||
All path properties are **optional**. Any property can be set to `null` or omitted entirely, and the system will fall back to environment variables or defaults.
|
||||
|
||||
| Property | Description | Equivalent CLI | Equivalent Env Var |
|
||||
|----------|-------------|----------------|-------------------|
|
||||
| `DataDir` | Database and data files | `--datadir` | `JELLYFIN_DATA_DIR` |
|
||||
| `ConfigDir` | Configuration files | `--configdir` | `JELLYFIN_CONFIG_DIR` |
|
||||
| `CacheDir` | Cache files | `--cachedir` | `JELLYFIN_CACHE_DIR` |
|
||||
| `LogDir` | Log files | `--logdir` | `JELLYFIN_LOG_DIR` |
|
||||
| `TempDir` | Temporary files | `--tempdir` | `JELLYFIN_TEMP_DIR` |
|
||||
| `WebDir` | Web client files | `--webdir` | `JELLYFIN_WEB_DIR` |
|
||||
|
||||
## Example Configurations
|
||||
|
||||
### Linux Production Server
|
||||
|
||||
```json
|
||||
{
|
||||
"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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Windows Production Server
|
||||
|
||||
```json
|
||||
{
|
||||
"Paths": {
|
||||
"DataDir": "C:\\ProgramData\\Jellyfin\\data",
|
||||
"ConfigDir": "C:\\ProgramData\\Jellyfin\\config",
|
||||
"CacheDir": "D:\\Cache\\Jellyfin",
|
||||
"LogDir": "C:\\ProgramData\\Jellyfin\\logs",
|
||||
"TempDir": "D:\\Temp\\Jellyfin",
|
||||
"WebDir": "C:\\Program Files\\Jellyfin\\web"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Development Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"Paths": {
|
||||
"DataDir": "./dev-data",
|
||||
"ConfigDir": "./dev-config",
|
||||
"CacheDir": "./dev-cache",
|
||||
"LogDir": "./dev-logs",
|
||||
"TempDir": "./dev-temp",
|
||||
"WebDir": "./wwwroot"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Minimal Configuration (Using Defaults)
|
||||
|
||||
```json
|
||||
{
|
||||
"Paths": {
|
||||
"DataDir": "/custom/jellyfin/data"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In this example, only `DataDir` is overridden. All other paths will use their default values or environment variables.
|
||||
|
||||
### Partial Override with Environment Variables
|
||||
|
||||
**startup.json:**
|
||||
```json
|
||||
{
|
||||
"Paths": {
|
||||
"DataDir": "/var/lib/jellyfin",
|
||||
"ConfigDir": "/etc/jellyfin"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Environment variables:**
|
||||
```bash
|
||||
export JELLYFIN_TEMP_DIR=/fast-storage/jellyfin-temp
|
||||
```
|
||||
|
||||
**Result:** DataDir and ConfigDir come from the file, TempDir from environment variable, and all others use defaults.
|
||||
|
||||
## Use Cases
|
||||
|
||||
### 1. Containerized Deployments
|
||||
|
||||
**Docker Example:**
|
||||
Create `startup.json` in your config volume:
|
||||
|
||||
```json
|
||||
{
|
||||
"Paths": {
|
||||
"DataDir": "/data",
|
||||
"ConfigDir": "/config",
|
||||
"CacheDir": "/cache",
|
||||
"LogDir": "/logs",
|
||||
"TempDir": "/temp"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**docker-compose.yml:**
|
||||
```yaml
|
||||
version: '3.8'
|
||||
services:
|
||||
jellyfin:
|
||||
image: jellyfin/jellyfin
|
||||
volumes:
|
||||
- ./startup.json:/config/startup.json
|
||||
- jellyfin_data:/data
|
||||
- jellyfin_cache:/cache
|
||||
- jellyfin_logs:/logs
|
||||
- jellyfin_temp:/temp
|
||||
```
|
||||
|
||||
### 2. Multiple Instance Setup
|
||||
|
||||
Run multiple Jellyfin instances with different configurations:
|
||||
|
||||
**Instance 1 (startup-prod.json):**
|
||||
```json
|
||||
{
|
||||
"Paths": {
|
||||
"DataDir": "/srv/jellyfin/prod/data",
|
||||
"ConfigDir": "/srv/jellyfin/prod/config",
|
||||
"LogDir": "/srv/jellyfin/prod/logs"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Instance 2 (startup-test.json):**
|
||||
```json
|
||||
{
|
||||
"Paths": {
|
||||
"DataDir": "/srv/jellyfin/test/data",
|
||||
"ConfigDir": "/srv/jellyfin/test/config",
|
||||
"LogDir": "/srv/jellyfin/test/logs"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Portable Installation
|
||||
|
||||
Create a portable Jellyfin installation with relative paths:
|
||||
|
||||
```json
|
||||
{
|
||||
"Paths": {
|
||||
"DataDir": "./data",
|
||||
"ConfigDir": "./config",
|
||||
"CacheDir": "./cache",
|
||||
"LogDir": "./logs",
|
||||
"TempDir": "./temp",
|
||||
"WebDir": "./web"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Performance Optimization
|
||||
|
||||
Place different directories on different storage devices:
|
||||
|
||||
```json
|
||||
{
|
||||
"Paths": {
|
||||
"DataDir": "/mnt/hdd/jellyfin/data",
|
||||
"ConfigDir": "/mnt/ssd/jellyfin/config",
|
||||
"CacheDir": "/mnt/ssd/jellyfin/cache",
|
||||
"TempDir": "/mnt/nvme/jellyfin/temp",
|
||||
"LogDir": "/mnt/hdd/jellyfin/logs"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
When Jellyfin starts, it will log the configuration file being used:
|
||||
|
||||
```
|
||||
Loaded startup configuration from: /path/to/startup.json
|
||||
```
|
||||
|
||||
If the file has syntax errors, you'll see:
|
||||
|
||||
```
|
||||
Warning: Failed to load startup configuration from /path/to/startup.json: [error message]
|
||||
```
|
||||
|
||||
All resolved paths are logged at startup:
|
||||
|
||||
```
|
||||
[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
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Configuration File Not Found
|
||||
|
||||
If your configuration file isn't being loaded:
|
||||
|
||||
1. Check the file is named exactly `startup.json`
|
||||
2. Verify it's in one of the search locations
|
||||
3. Check file permissions (must be readable)
|
||||
4. Look for typos in the JSON structure
|
||||
|
||||
### Invalid JSON Syntax
|
||||
|
||||
Common JSON errors:
|
||||
|
||||
```json
|
||||
// ❌ Wrong - trailing comma
|
||||
{
|
||||
"Paths": {
|
||||
"DataDir": "/var/lib/jellyfin",
|
||||
}
|
||||
}
|
||||
|
||||
// ✅ Correct
|
||||
{
|
||||
"Paths": {
|
||||
"DataDir": "/var/lib/jellyfin"
|
||||
}
|
||||
}
|
||||
|
||||
// ❌ Wrong - single quotes
|
||||
{
|
||||
"Paths": {
|
||||
'DataDir': '/var/lib/jellyfin'
|
||||
}
|
||||
}
|
||||
|
||||
// ✅ Correct - double quotes
|
||||
{
|
||||
"Paths": {
|
||||
"DataDir": "/var/lib/jellyfin"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Path Resolution Order
|
||||
|
||||
Remember the priority:
|
||||
1. CLI argument beats everything
|
||||
2. Environment variable beats config file
|
||||
3. Config file beats defaults
|
||||
|
||||
To test which source is being used, try setting different values in each and check the startup logs.
|
||||
|
||||
## Migration from Environment Variables
|
||||
|
||||
If you currently use environment variables, you can migrate to a config file:
|
||||
|
||||
**Before (environment variables):**
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
**After (startup.json):**
|
||||
```json
|
||||
{
|
||||
"Paths": {
|
||||
"DataDir": "/var/lib/jellyfin",
|
||||
"ConfigDir": "/etc/jellyfin",
|
||||
"CacheDir": "/var/cache/jellyfin",
|
||||
"LogDir": "/var/log/jellyfin"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then remove the environment variables from your `.bashrc`, systemd service, or wherever they're defined.
|
||||
|
||||
## Benefits
|
||||
|
||||
### Advantages of File-Based Configuration
|
||||
|
||||
1. **Portability**: Easy to copy configuration between systems
|
||||
2. **Version Control**: Track configuration changes in Git
|
||||
3. **Documentation**: Self-documenting with comments (in extended formats)
|
||||
4. **Persistence**: Survives system reboots and shell sessions
|
||||
5. **Consistency**: Same configuration across all instances
|
||||
6. **No Shell Escaping**: No need to worry about shell quoting rules
|
||||
7. **Easy Editing**: Simple text file, easy to modify
|
||||
8. **Backup**: Can be backed up with other configuration files
|
||||
|
||||
### When to Use Each Method
|
||||
|
||||
| Method | Best For |
|
||||
|--------|----------|
|
||||
| **Config File** | Production servers, containers, permanent installations |
|
||||
| **Environment Variables** | System-wide settings, CI/CD pipelines, user-specific overrides |
|
||||
| **Command Line** | Testing, one-time overrides, debugging |
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- Keep `startup.json` readable only by the Jellyfin user
|
||||
- Don't commit sensitive paths to public repositories
|
||||
- Use environment variables for secrets (like database passwords)
|
||||
- Consider using separate config files per environment (dev/staging/prod)
|
||||
|
||||
## Example Setup Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# create-jellyfin-config.sh
|
||||
|
||||
cat > /etc/jellyfin/startup.json <<EOF
|
||||
{
|
||||
"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"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
|
||||
# Set proper permissions
|
||||
chmod 644 /etc/jellyfin/startup.json
|
||||
chown jellyfin:jellyfin /etc/jellyfin/startup.json
|
||||
|
||||
echo "Jellyfin startup configuration created at /etc/jellyfin/startup.json"
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [PATH_CONFIGURATION_GUIDE.md](PATH_CONFIGURATION_GUIDE.md) - Complete path configuration reference
|
||||
- [startup.json.example](startup.json.example) - Template configuration file with JSON schema
|
||||
Reference in New Issue
Block a user