pgsql-jellyfin/docs/AUTO_GENERATED_STARTUP_CONFIG.md

Auto-Generated Startup Configuration

Overview

As of this update, Jellyfin automatically creates a startup.json configuration file on first startup if one doesn't already exist. This makes it easier for new users to get started with file-based path configuration.

Automatic Creation

When It's Created

The startup.json file is automatically created when:

1. Jellyfin starts for the first time
2. No existing startup.json file is found in any of the search locations
3. The application has write permissions to the directory

Where It's Created

The file is created in the current working directory by default:

• Development: Where you run dotnet run from
• Installed: The Jellyfin installation directory
• Service: Typically the service's working directory (e.g., /opt/jellyfin)
• Docker: The working directory inside the container

Search order for existing files:

1. Current working directory: ./startup.json
2. Application directory: {AppDir}/startup.json
3. Config subdirectory: {AppDir}/config/startup.json

What It Contains

The auto-generated file includes:

{
  "_comment": "Jellyfin Startup Configuration - Configure path locations for Jellyfin data, logs, cache, and more.",
  "_documentation": "See FILE_BASED_STARTUP_CONFIG.md for complete documentation",
  "_priority": "Command-line options > Environment variables > This file > Defaults",
  "Paths": {
    "DataDir": null,
    "ConfigDir": null,
    "CacheDir": null,
    "LogDir": null,
    "TempDir": null,
    "WebDir": null
  },
  "Examples": {
    "_comment": "Example configurations below - remove this Examples section when customizing",
    "Linux": {
      "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": {
      "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"
    },
    "Portable": {
      "DataDir": "./data",
      "ConfigDir": "./config",
      "CacheDir": "./cache",
      "LogDir": "./logs",
      "TempDir": "./temp",
      "WebDir": "./web"
    }
  }
}

Features

1. Self-Documenting

• Includes comments explaining purpose and priority
• References full documentation
• Shows examples for different platforms

2. Ready to Customize

• All path properties set to null by default (uses system defaults)
• Remove null and add your custom paths
• Remove the Examples section after customizing

3. Platform Examples

• Linux - Standard Linux FHS paths
• Windows - Windows Program Data paths
• Portable - Relative paths for portable installations

Customization

Quick Start

1. After first startup, you'll see:

   Created default startup configuration at: /path/to/startup.json
   You can customize this file to set default paths for Jellyfin.
   

2. Edit the file to add your custom paths:

   {
     "Paths": {
       "DataDir": "/var/lib/jellyfin",
       "ConfigDir": "/etc/jellyfin",
       "LogDir": "/var/log/jellyfin"
     }
   }
   

3. Remove unused properties and examples:

   {
     "Paths": {
       "DataDir": "/custom/path"
     }
   }
   

4. Restart Jellyfin to apply changes

Using Examples

To use one of the example configurations:

Linux:

{
  "Paths": {
    "DataDir": "/var/lib/jellyfin",
    "ConfigDir": "/etc/jellyfin",
    "CacheDir": "/var/cache/jellyfin",
    "LogDir": "/var/log/jellyfin",
    "TempDir": "/var/tmp/jellyfin"
  }
}

Windows:

{
  "Paths": {
    "DataDir": "C:\\ProgramData\\Jellyfin\\data",
    "ConfigDir": "C:\\ProgramData\\Jellyfin\\config",
    "LogDir": "C:\\ProgramData\\Jellyfin\\logs"
  }
}

Portable:

{
  "Paths": {
    "DataDir": "./data",
    "ConfigDir": "./config",
    "CacheDir": "./cache"
  }
}

Startup Messages

File Created

Created default startup configuration at: /path/to/startup.json
You can customize this file to set default paths for Jellyfin.

File Loaded

Loaded startup configuration from: /path/to/startup.json

Creation Failed

Warning: Could not create default startup configuration: [error message]

This is not fatal - Jellyfin will continue using defaults or environment variables/command-line options.

Preventing Auto-Creation

If you don't want the file to be auto-created:

1. Create an empty file before starting:

   touch startup.json
   echo "{}" > startup.json
   

2. Use environment variables or command-line options instead of file-based config

3. Check file permissions - File won't be created if directory isn't writable

File Locations by Installation Type

Standard Installation (Linux)

/opt/jellyfin/startup.json

Systemd Service

/etc/jellyfin/startup.json
# or
/usr/lib/jellyfin/startup.json

Windows Installed

C:\Program Files\Jellyfin\Server\startup.json

Portable Installation

./startup.json  (same directory as jellyfin.exe or jellyfin)

Docker Container

/app/startup.json  (inside container)
# or mount from host:
docker run -v /path/to/startup.json:/app/startup.json ...

Configuration Priority

Remember, the file-based configuration has this priority:

1. Command-line options (highest) - --datadir /path
2. Environment variables - JELLYFIN_DATA_DIR=/path
3. Configuration file - startup.json
4. Defaults (lowest) - OS-specific defaults

So even with a startup.json file, you can still override settings with environment variables or command-line options.

Integration with Other Configuration

Works With

• ✅ database.xml - Database configuration
• ✅ system.xml - System settings
• ✅ logging.json - Logging configuration
• ✅ Environment variables - Can override paths
• ✅ Command-line options - Can override paths

Independent From

• Database selection (SQLite vs PostgreSQL)
• Web client hosting
• Network configuration
• Plugin settings

Troubleshooting

File Not Created

Possible Causes:

1. Directory isn't writable
2. File already exists (check search locations)
3. Insufficient permissions

Solution:

# Check permissions
ls -la ./startup.json

# Create manually if needed
cp startup.json.example startup.json

# Set proper permissions
chmod 644 startup.json

File Ignored

Check:

1. File is valid JSON (no syntax errors)
2. File is in one of the search locations
3. Properties are correctly named (case-sensitive)
4. No environment variables or CLI options overriding

Example Section Causing Issues

The Examples section is ignored by the configuration parser - it's just for reference. You can safely remove it:

{
  "Paths": {
    "DataDir": "/custom/path"
  }
}

Migration from Manual Creation

If you previously created startup.json manually:

1. Your file is preserved - Auto-creation only happens if no file exists
2. Your settings continue to work - No changes needed
3. You can add examples from the auto-generated template if desired

Security Considerations

1. File Permissions

   chmod 644 startup.json
   chown jellyfin:jellyfin startup.json
   

2. No Sensitive Data

   • The file doesn't contain passwords
   • Only paths are stored
   • Safe to commit to version control

3. Read-Only Option

   # Make read-only after customizing
   chmod 444 startup.json
   

Docker Considerations

Option 1: Let Docker Create It

docker run -v jellyfin-config:/config jellyfin/jellyfin
# startup.json created inside container

Option 2: Mount Pre-Created File

docker run -v /host/path/startup.json:/app/startup.json:ro jellyfin/jellyfin

Option 3: Use Environment Variables

docker run -e JELLYFIN_DATA_DIR=/data -e JELLYFIN_CONFIG_DIR=/config jellyfin/jellyfin

Benefits

1. ✅ First-Time Experience - New users get a template automatically
2. ✅ Self-Documenting - Examples and comments included
3. ✅ No Manual Download - No need to find example files
4. ✅ Platform Aware - Examples for Linux, Windows, and portable setups
5. ✅ Non-Intrusive - Only created if missing
6. ✅ Safe Defaults - All paths null means use system defaults

See Also

• FILE_BASED_STARTUP_CONFIG.md - Complete configuration guide
• PATH_CONFIGURATION_GUIDE.md - Path configuration reference
• startup.json.example - Example configuration file
• DATABASE_CONFIGURATION_GUIDE.md - Database setup