pgsql-jellyfin/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:

```json
{
  "_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:
   ```json
   {
     "Paths": {
       "DataDir": "/var/lib/jellyfin",
       "ConfigDir": "/etc/jellyfin",
       "LogDir": "/var/log/jellyfin"
     }
   }
   ```

3. **Remove unused properties** and examples:
   ```json
   {
     "Paths": {
       "DataDir": "/custom/path"
     }
   }
   ```

4. **Restart Jellyfin** to apply changes

### Using Examples

To use one of the example configurations:

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

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

**Portable:**
```json
{
  "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:
   ```bash
   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:**
```bash
# 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:

```json
{
  "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**
   ```bash
   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**
   ```bash
   # Make read-only after customizing
   chmod 444 startup.json
   ```

## Docker Considerations

### Option 1: Let Docker Create It
```bash
docker run -v jellyfin-config:/config jellyfin/jellyfin
# startup.json created inside container
```

### Option 2: Mount Pre-Created File
```bash
docker run -v /host/path/startup.json:/app/startup.json:ro jellyfin/jellyfin
```

### Option 3: Use Environment Variables
```bash
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](FILE_BASED_STARTUP_CONFIG.md) - Complete configuration guide
- [PATH_CONFIGURATION_GUIDE.md](PATH_CONFIGURATION_GUIDE.md) - Path configuration reference
- [startup.json.example](startup.json.example) - Example configuration file
- [DATABASE_CONFIGURATION_GUIDE.md](DATABASE_CONFIGURATION_GUIDE.md) - Database setup