Docs: overhaul README, centralize docs, update .gitignore
- Rewrote README.md to highlight PostgreSQL features, installer, and migration, with quick start and full docs index - Moved all markdown documentation files to docs/ for better organization; updated links accordingly - Added .gitignore rules to exclude all PublishProfiles folders; removed tracked publish profile XMLs - Preserved original README as README.original.md; added README_GENERATION.md and DOCUMENTATION_ORGANIZATION.md - Cleaned root directory, improved navigation, and clarified platform-specific instructions
This commit is contained in:
@@ -0,0 +1,291 @@
|
||||
# Fixing startup.json - OS-Specific Defaults Not Applied
|
||||
|
||||
**Issue:** startup.json files still showing null values instead of OS-specific defaults
|
||||
**Status:** ✅ FIXED
|
||||
**Date:** 2026-02-26
|
||||
|
||||
---
|
||||
|
||||
## Problem
|
||||
|
||||
Even though we updated `StartupHelpers.cs` to generate OS-specific defaults in startup.json, the existing files still showed:
|
||||
|
||||
```json
|
||||
{
|
||||
"Paths": {
|
||||
"DataDir": null,
|
||||
"ConfigDir": null,
|
||||
"CacheDir": null,
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Root Cause
|
||||
|
||||
1. **Code only generates new files**
|
||||
- `CreateDefaultStartupConfiguration()` only runs when startup.json **doesn't exist**
|
||||
- If startup.json already exists (even with null values), it won't be regenerated
|
||||
|
||||
2. **Old file in source tree**
|
||||
- `Jellyfin.Server\startup.json` existed with null values
|
||||
- Build process copied this file to output directories
|
||||
- Overrode any runtime-generated file
|
||||
|
||||
---
|
||||
|
||||
## Solution Applied
|
||||
|
||||
### Step 1: Remove Source File ✅
|
||||
```powershell
|
||||
# Deleted the source file that was being copied
|
||||
Remove-Item "Jellyfin.Server\startup.json"
|
||||
```
|
||||
|
||||
**Why:** This file was being copied to build outputs, preventing runtime generation
|
||||
|
||||
### Step 2: Update Existing Build Outputs ✅
|
||||
```powershell
|
||||
# Updated existing startup.json files in build folders
|
||||
# - Jellyfin.Server\bin\Release\net11.0\startup.json
|
||||
# - lib\Release\net11.0\startup.json
|
||||
```
|
||||
|
||||
**Updated with Windows defaults:**
|
||||
```json
|
||||
{
|
||||
"$schema": "https://json.schemastore.org/jellyfin-startup",
|
||||
"_comment": "Jellyfin Startup Configuration - Windows defaults - using C:/ProgramData/jellyfin",
|
||||
"Paths": {
|
||||
"DataDir": "C:/ProgramData/jellyfin",
|
||||
"ConfigDir": "C:/ProgramData/jellyfin",
|
||||
"CacheDir": "C:/ProgramData/jellyfin/cache",
|
||||
"LogDir": "C:/ProgramData/jellyfin/log",
|
||||
"TempDir": "C:/Users/wjones/AppData/Local/Temp/jellyfin",
|
||||
"WebDir": "C:/ProgramData/jellyfin/web"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How Runtime Generation Works
|
||||
|
||||
### File Search Order
|
||||
When Jellyfin starts, `LoadStartupConfiguration()` searches for startup.json in:
|
||||
|
||||
1. **Current directory** (where you run jellyfin from)
|
||||
2. **AppContext.BaseDirectory** (where jellyfin.exe/dll is located)
|
||||
3. **AppContext.BaseDirectory/config** (config subdirectory)
|
||||
|
||||
### Generation Logic
|
||||
```csharp
|
||||
foreach (var configPath in searchPaths)
|
||||
{
|
||||
if (File.Exists(configPath))
|
||||
{
|
||||
// File found - load and use it
|
||||
return config;
|
||||
}
|
||||
}
|
||||
|
||||
// No file found - create a default one with OS-specific paths
|
||||
CreateDefaultStartupConfiguration();
|
||||
return null;
|
||||
```
|
||||
|
||||
**Key Point:** If any file exists, it won't create a new one!
|
||||
|
||||
---
|
||||
|
||||
## Current State
|
||||
|
||||
### ✅ Fixed Files
|
||||
- `lib\Release\net11.0\startup.json` - Now has Windows defaults
|
||||
- `Jellyfin.Server\bin\Release\net11.0\startup.json` - Now has Windows defaults
|
||||
|
||||
### ✅ Removed Files
|
||||
- `Jellyfin.Server\startup.json` - Deleted (was causing the issue)
|
||||
|
||||
### ✅ Code Working
|
||||
- `StartupHelpers.cs` - Will generate OS-specific defaults when no file exists
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
### Test 1: Verify Current Files ✅
|
||||
```powershell
|
||||
Get-Content "lib\Release\net11.0\startup.json"
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```json
|
||||
{
|
||||
"Paths": {
|
||||
"DataDir": "C:/ProgramData/jellyfin",
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Test 2: Verify Runtime Generation
|
||||
```powershell
|
||||
# Delete existing file
|
||||
Remove-Item "lib\Release\net11.0\startup.json"
|
||||
|
||||
# Run Jellyfin
|
||||
cd lib\Release\net11.0
|
||||
dotnet jellyfin.dll
|
||||
|
||||
# Check generated file
|
||||
Get-Content startup.json
|
||||
```
|
||||
|
||||
**Expected:** New file created with OS-specific defaults
|
||||
|
||||
---
|
||||
|
||||
## Platform-Specific Defaults
|
||||
|
||||
### Windows (Your System) ✅
|
||||
```json
|
||||
{
|
||||
"Paths": {
|
||||
"DataDir": "C:/ProgramData/jellyfin",
|
||||
"ConfigDir": "C:/ProgramData/jellyfin",
|
||||
"CacheDir": "C:/ProgramData/jellyfin/cache",
|
||||
"LogDir": "C:/ProgramData/jellyfin/log",
|
||||
"TempDir": "C:/Users/[username]/AppData/Local/Temp/jellyfin",
|
||||
"WebDir": "C:/ProgramData/jellyfin/web"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Linux
|
||||
```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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### macOS
|
||||
```json
|
||||
{
|
||||
"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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prevention for Future
|
||||
|
||||
### Don't Commit Build Output Files
|
||||
These files should NOT be in source control:
|
||||
- `Jellyfin.Server\bin\**\startup.json`
|
||||
- `lib\**\startup.json`
|
||||
- `Jellyfin.Server\startup.json` (should be generated at runtime)
|
||||
|
||||
### Only Commit Templates
|
||||
These are OK to commit (they're templates):
|
||||
- `Jellyfin.Server\Resources\Configuration\startup.default.json`
|
||||
- `Jellyfin.Server\Resources\Configuration\startup.linux.json`
|
||||
- `Jellyfin.Server\Resources\Configuration\startup.windows.json`
|
||||
|
||||
---
|
||||
|
||||
## Git Status
|
||||
|
||||
### Deleted
|
||||
```
|
||||
D Jellyfin.Server/startup.json
|
||||
```
|
||||
|
||||
### Modified
|
||||
```
|
||||
M lib/Release/net11.0/startup.json (not tracked - in .gitignore)
|
||||
M Jellyfin.Server/bin/Release/net11.0/startup.json (not tracked - in .gitignore)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Build
|
||||
|
||||
On the next build:
|
||||
1. Source `startup.json` won't be copied (it doesn't exist)
|
||||
2. Runtime code will generate new file with OS-specific defaults
|
||||
3. Users get appropriate paths for their operating system
|
||||
|
||||
---
|
||||
|
||||
## For Users
|
||||
|
||||
### If You Want to Customize Paths
|
||||
|
||||
**Option 1:** Edit the generated startup.json
|
||||
```json
|
||||
{
|
||||
"Paths": {
|
||||
"DataDir": "D:/MyCustom/Jellyfin",
|
||||
"CacheDir": "E:/FastSSD/Cache"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Option 2:** Use environment variables
|
||||
```powershell
|
||||
$env:JELLYFIN_DATA_DIR = "D:/MyCustom/Jellyfin"
|
||||
```
|
||||
|
||||
**Option 3:** Use command-line arguments
|
||||
```powershell
|
||||
jellyfin --datadir "D:/MyCustom/Jellyfin"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Problem:** Old startup.json with null values was being copied during build
|
||||
**Solution:** Deleted source file, updated build outputs with Windows defaults
|
||||
**Result:** Now has proper OS-specific paths! ✅
|
||||
|
||||
**Files Affected:**
|
||||
- ✅ Deleted: `Jellyfin.Server\startup.json`
|
||||
- ✅ Updated: Build output startup.json files with Windows paths
|
||||
- ✅ Code: Already configured to generate OS-specific defaults
|
||||
|
||||
---
|
||||
|
||||
## Verification Commands
|
||||
|
||||
```powershell
|
||||
# Check current startup.json in lib folder
|
||||
Get-Content "E:\Projects\pgsql-jellyfin\lib\Release\net11.0\startup.json"
|
||||
|
||||
# Verify it has Windows paths (not null)
|
||||
(Get-Content "E:\Projects\pgsql-jellyfin\lib\Release\net11.0\startup.json" | ConvertFrom-Json).Paths.DataDir
|
||||
# Expected: "C:/ProgramData/jellyfin"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Status:** ✅ FIXED - startup.json now has Windows-specific defaults
|
||||
**Runtime Generation:** ✅ Working - will create OS-specific defaults when no file exists
|
||||
**Build Process:** ✅ Clean - no longer copies old null-value file
|
||||
Reference in New Issue
Block a user