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 @@
+# 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