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
This commit is contained in:
@@ -0,0 +1,299 @@
|
||||
# OS-Specific startup.json Generation
|
||||
|
||||
## Overview
|
||||
The `startup.json` file is now automatically generated with **OS-specific default paths** instead of null values.
|
||||
|
||||
---
|
||||
|
||||
## Generated Content by Operating System
|
||||
|
||||
### Windows Example
|
||||
When Jellyfin starts on Windows and no `startup.json` exists, it creates:
|
||||
|
||||
```json
|
||||
{
|
||||
"_comment": "Jellyfin Startup Configuration - Windows defaults - using C:/ProgramData/jellyfin",
|
||||
"_note": "These paths will be used unless overridden by environment variables or command-line arguments",
|
||||
"_priority": "Command-line args > Environment variables > This file > Built-in defaults",
|
||||
"_examples": "See startup.linux.json or startup.windows.json in Resources/Configuration for other OS examples",
|
||||
"Paths": {
|
||||
"DataDir": "C:/ProgramData/jellyfin",
|
||||
"ConfigDir": "C:/ProgramData/jellyfin",
|
||||
"CacheDir": "C:/ProgramData/jellyfin/cache",
|
||||
"LogDir": "C:/ProgramData/jellyfin/log",
|
||||
"TempDir": "C:/Users/<user>/AppData/Local/Temp/jellyfin",
|
||||
"WebDir": "C:/ProgramData/jellyfin/web"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Linux Example
|
||||
When Jellyfin starts on Linux and no `startup.json` exists, it creates:
|
||||
|
||||
```json
|
||||
{
|
||||
"_comment": "Jellyfin Startup Configuration - Linux defaults - following Filesystem Hierarchy Standard (FHS)",
|
||||
"_note": "These paths will be used unless overridden by environment variables or command-line arguments",
|
||||
"_priority": "Command-line args > Environment variables > This file > Built-in defaults",
|
||||
"_examples": "See startup.linux.json or startup.windows.json in Resources/Configuration for other OS examples",
|
||||
"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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### macOS Example
|
||||
When Jellyfin starts on macOS and no `startup.json` exists, it creates:
|
||||
|
||||
```json
|
||||
{
|
||||
"_comment": "Jellyfin Startup Configuration - macOS defaults - using user Library paths",
|
||||
"_note": "These paths will be used unless overridden by environment variables or command-line arguments",
|
||||
"_priority": "Command-line args > Environment variables > This file > Built-in defaults",
|
||||
"_examples": "See startup.linux.json or startup.windows.json in Resources/Configuration for other OS examples",
|
||||
"Paths": {
|
||||
"DataDir": "~/Library/Application Support/jellyfin",
|
||||
"ConfigDir": "~/Library/Application Support/jellyfin/config",
|
||||
"CacheDir": "~/Library/Caches/jellyfin",
|
||||
"LogDir": "~/Library/Logs/jellyfin",
|
||||
"TempDir": "/tmp/jellyfin",
|
||||
"WebDir": "~/Library/Application Support/jellyfin/web"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Portable/Unknown OS Example
|
||||
When Jellyfin starts on an unknown OS and no `startup.json` exists, it creates:
|
||||
|
||||
```json
|
||||
{
|
||||
"_comment": "Jellyfin Startup Configuration - Portable defaults - using relative paths",
|
||||
"_note": "These paths will be used unless overridden by environment variables or command-line arguments",
|
||||
"_priority": "Command-line args > Environment variables > This file > Built-in defaults",
|
||||
"_examples": "See startup.linux.json or startup.windows.json in Resources/Configuration for other OS examples",
|
||||
"Paths": {
|
||||
"DataDir": "./data",
|
||||
"ConfigDir": "./config",
|
||||
"CacheDir": "./cache",
|
||||
"LogDir": "./logs",
|
||||
"TempDir": "./temp",
|
||||
"WebDir": "./web"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Platform Standards Followed
|
||||
|
||||
### Windows
|
||||
- **Standard Location:** `C:/ProgramData/jellyfin`
|
||||
- **Rationale:** ProgramData is the Windows standard for application data shared across all users
|
||||
- **Permissions:** Requires administrator rights for initial setup
|
||||
|
||||
### Linux
|
||||
- **Standard:** Filesystem Hierarchy Standard (FHS)
|
||||
- **Rationale:** Follows Linux best practices for system-wide installations
|
||||
- **Paths:**
|
||||
- `/var/lib/jellyfin` - Application data
|
||||
- `/etc/jellyfin` - Configuration files
|
||||
- `/var/cache/jellyfin` - Cache files
|
||||
- `/var/log/jellyfin` - Log files
|
||||
- `/var/tmp/jellyfin` - Temporary files
|
||||
- `/usr/share/jellyfin/web` - Web UI assets
|
||||
|
||||
### macOS
|
||||
- **Standard Location:** User's Library folder
|
||||
- **Rationale:** Follows Apple's guidelines for user-specific applications
|
||||
- **Paths follow:** macOS file system conventions
|
||||
|
||||
### Portable
|
||||
- **Standard:** Relative paths
|
||||
- **Rationale:** For USB/portable installations
|
||||
- **Benefit:** No system-wide installation required
|
||||
|
||||
---
|
||||
|
||||
## Behavior
|
||||
|
||||
### When `startup.json` Doesn't Exist
|
||||
1. Jellyfin detects no configuration file
|
||||
2. Calls `CreateDefaultStartupConfiguration()`
|
||||
3. Detects current operating system
|
||||
4. Generates appropriate default paths
|
||||
5. Creates `startup.json` in current directory
|
||||
6. Displays message to console
|
||||
7. Uses these paths for startup
|
||||
|
||||
### When `startup.json` Exists
|
||||
- Uses existing configuration
|
||||
- No automatic generation
|
||||
- Respects user customizations
|
||||
|
||||
---
|
||||
|
||||
## Console Output
|
||||
|
||||
### On First Run (Windows)
|
||||
```
|
||||
Created default startup configuration at: E:\Jellyfin\startup.json
|
||||
Using Windows defaults - using C:/ProgramData/jellyfin
|
||||
You can customize this file to set different paths for Jellyfin.
|
||||
```
|
||||
|
||||
### On First Run (Linux)
|
||||
```
|
||||
Created default startup configuration at: /opt/jellyfin/startup.json
|
||||
Using Linux defaults - following Filesystem Hierarchy Standard (FHS)
|
||||
You can customize this file to set different paths for Jellyfin.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Priority Order
|
||||
|
||||
Jellyfin resolves paths in this priority order:
|
||||
|
||||
1. **Command-line arguments** (Highest)
|
||||
```bash
|
||||
jellyfin --datadir /custom/path
|
||||
```
|
||||
|
||||
2. **Environment variables**
|
||||
```bash
|
||||
export JELLYFIN_DATA_DIR=/custom/path
|
||||
```
|
||||
|
||||
3. **startup.json file**
|
||||
```json
|
||||
{ "Paths": { "DataDir": "/custom/path" } }
|
||||
```
|
||||
|
||||
4. **Built-in OS defaults** (Lowest)
|
||||
- Determined by `CreateApplicationPaths()` method
|
||||
|
||||
---
|
||||
|
||||
## Customization Examples
|
||||
|
||||
### Change Just the Data Directory
|
||||
```json
|
||||
{
|
||||
"Paths": {
|
||||
"DataDir": "/mnt/storage/jellyfin",
|
||||
"ConfigDir": "/etc/jellyfin",
|
||||
"CacheDir": "/var/cache/jellyfin",
|
||||
"LogDir": "/var/log/jellyfin",
|
||||
"TempDir": "/var/tmp/jellyfin",
|
||||
"WebDir": "/usr/share/jellyfin/web"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Use All Custom Paths
|
||||
```json
|
||||
{
|
||||
"Paths": {
|
||||
"DataDir": "D:/Media/Jellyfin/Data",
|
||||
"ConfigDir": "D:/Media/Jellyfin/Config",
|
||||
"CacheDir": "E:/Cache/Jellyfin",
|
||||
"LogDir": "D:/Logs/Jellyfin",
|
||||
"TempDir": "F:/Temp/Jellyfin",
|
||||
"WebDir": "C:/Program Files/Jellyfin/Web"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Portable Installation
|
||||
```json
|
||||
{
|
||||
"Paths": {
|
||||
"DataDir": "./data",
|
||||
"ConfigDir": "./config",
|
||||
"CacheDir": "./cache",
|
||||
"LogDir": "./logs",
|
||||
"TempDir": "./temp",
|
||||
"WebDir": "./web"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
✅ **No manual configuration needed** - Works out of the box
|
||||
✅ **OS-appropriate defaults** - Follows platform conventions
|
||||
✅ **Easy to customize** - Edit one JSON file
|
||||
✅ **Clear documentation** - Comments explain what to change
|
||||
✅ **Cross-platform** - Same behavior on all platforms
|
||||
✅ **Backward compatible** - Existing startup.json files still work
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
### Test on Windows
|
||||
1. Delete existing `startup.json`
|
||||
2. Run Jellyfin
|
||||
3. Check that `startup.json` was created with Windows paths
|
||||
4. Verify Jellyfin uses `C:/ProgramData/jellyfin`
|
||||
|
||||
### Test on Linux
|
||||
1. Delete existing `startup.json`
|
||||
2. Run Jellyfin
|
||||
3. Check that `startup.json` was created with Linux FHS paths
|
||||
4. Verify Jellyfin uses `/var/lib/jellyfin`, `/etc/jellyfin`, etc.
|
||||
|
||||
### Test Customization
|
||||
1. Create `startup.json` with custom paths
|
||||
2. Run Jellyfin
|
||||
3. Verify it uses your custom paths
|
||||
4. No new file should be generated
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Code:** `Jellyfin.Server/Helpers/StartupHelpers.cs`
|
||||
- **Method:** `CreateDefaultStartupConfiguration()`
|
||||
- **Templates:**
|
||||
- `Jellyfin.Server/Resources/Configuration/startup.linux.json`
|
||||
- `Jellyfin.Server/Resources/Configuration/startup.windows.json`
|
||||
- `Jellyfin.Server/Resources/Configuration/startup.default.json`
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### File Not Created
|
||||
**Issue:** startup.json not being created
|
||||
**Solution:** Check write permissions in current directory
|
||||
|
||||
### Wrong OS Detected
|
||||
**Issue:** Getting incorrect OS-specific paths
|
||||
**Solution:** Check `OperatingSystem.IsWindows()`, etc. detection
|
||||
|
||||
### Want Different Defaults
|
||||
**Issue:** Don't like the auto-generated defaults
|
||||
**Solution:** Just edit the `startup.json` file - it won't be regenerated
|
||||
|
||||
---
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- 📋 Add interactive setup wizard
|
||||
- 📋 Add validation for path accessibility
|
||||
- 📋 Add migration tool for moving data between paths
|
||||
- 📋 Add path recommendations based on available storage
|
||||
|
||||
---
|
||||
|
||||
**Status:** ✅ Production Ready
|
||||
**Build:** ✅ Successful
|
||||
**Testing:** Ready for user testing
|
||||
Reference in New Issue
Block a user