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,167 @@
|
||||
# PostgreSQL Backup Logging - External Tool References
|
||||
|
||||
## Overview
|
||||
|
||||
All logging messages have been updated to explicitly clarify that `pg_dump` and `pg_restore` are **external command-line tools** being executed as separate processes, not internal library functions.
|
||||
|
||||
## Updated Log Messages
|
||||
|
||||
### PostgresBackupService.cs
|
||||
|
||||
#### Backup Creation:
|
||||
```csharp
|
||||
// Before:
|
||||
"Starting PostgreSQL backup to {BackupPath}"
|
||||
"Executing: {PgDump} {Arguments}"
|
||||
"Successfully created PostgreSQL backup at {BackupPath}"
|
||||
|
||||
// After:
|
||||
"Starting PostgreSQL backup using external pg_dump tool to {BackupPath}"
|
||||
"Executing external command: {PgDump} {Arguments}"
|
||||
"Successfully created PostgreSQL backup using external pg_dump at {BackupPath}"
|
||||
```
|
||||
|
||||
#### Backup Restoration:
|
||||
```csharp
|
||||
// Before:
|
||||
"Starting PostgreSQL restore from {BackupPath}"
|
||||
"Successfully restored PostgreSQL backup from {BackupPath}"
|
||||
|
||||
// After:
|
||||
"Starting PostgreSQL restore using external pg_restore tool from {BackupPath}"
|
||||
"Successfully restored PostgreSQL backup using external pg_restore from {BackupPath}"
|
||||
```
|
||||
|
||||
#### Backup Deletion:
|
||||
```csharp
|
||||
// Before (in PostgresDatabaseProvider):
|
||||
"Deleted local PostgreSQL backup: {BackupPath}"
|
||||
|
||||
// After:
|
||||
"Deleted local PostgreSQL backup created by external pg_dump: {BackupPath}"
|
||||
```
|
||||
|
||||
#### Error Messages:
|
||||
```csharp
|
||||
// Before:
|
||||
"{defaultExecutableName} executable not found. Please configure the path in database.xml or ensure it's in the system PATH."
|
||||
|
||||
// After:
|
||||
"External {defaultExecutableName} executable not found. Please configure the path in database.xml or ensure PostgreSQL client tools are installed and in the system PATH."
|
||||
```
|
||||
|
||||
### PostgresDatabaseProvider.cs
|
||||
|
||||
#### Initialization Messages:
|
||||
```csharp
|
||||
// Before:
|
||||
"PostgreSQL backup service initialized for local database"
|
||||
"PostgreSQL database is on remote server ({Host}). Backup operations via pg_dump/pg_restore are disabled"
|
||||
|
||||
// After:
|
||||
"PostgreSQL backup service initialized for local database (will use external pg_dump/pg_restore tools)"
|
||||
"PostgreSQL database is on remote server ({Host}). Backup operations via external pg_dump/pg_restore tools are disabled"
|
||||
```
|
||||
|
||||
#### Backup Operation Messages:
|
||||
```csharp
|
||||
// Before:
|
||||
"PostgreSQL local backup created: {BackupPath}"
|
||||
"Failed to create local PostgreSQL backup using pg_dump"
|
||||
"Fast backup is not implemented for PostgreSQL on a remote server. Use pg_dump manually..."
|
||||
|
||||
// After:
|
||||
"PostgreSQL local backup created using external pg_dump: {BackupPath}"
|
||||
"Failed to create local PostgreSQL backup using external pg_dump"
|
||||
"Fast backup is not implemented for PostgreSQL on a remote server. Use external pg_dump command manually..."
|
||||
```
|
||||
|
||||
#### Restore Operation Messages:
|
||||
```csharp
|
||||
// Before:
|
||||
"PostgreSQL local backup restored from: {BackupPath}"
|
||||
"Failed to restore local PostgreSQL backup using pg_restore"
|
||||
"Fast restore is not implemented for PostgreSQL on a remote server. Use pg_restore manually..."
|
||||
|
||||
// After:
|
||||
"PostgreSQL local backup restored using external pg_restore from: {BackupPath}"
|
||||
"Failed to restore local PostgreSQL backup using external pg_restore"
|
||||
"Fast restore is not implemented for PostgreSQL on a remote server. Use external pg_restore command manually..."
|
||||
```
|
||||
|
||||
#### Delete Operation Messages:
|
||||
```csharp
|
||||
// Before:
|
||||
"Failed to delete local PostgreSQL backup: {BackupKey}"
|
||||
"Backup deletion is not implemented for PostgreSQL on a remote server. Manage backups externally."
|
||||
|
||||
// After:
|
||||
"Failed to delete local PostgreSQL backup created by external pg_dump: {BackupKey}"
|
||||
"Backup deletion is not implemented for PostgreSQL on a remote server. Manage backups created by external pg_dump/pg_restore manually."
|
||||
```
|
||||
|
||||
## Complete Log Flow Examples
|
||||
|
||||
### Successful Local Backup:
|
||||
```
|
||||
[INFO] PostgreSQL backup service initialized for local database (will use external pg_dump/pg_restore tools)
|
||||
[INFO] Starting PostgreSQL backup using external pg_dump tool to /data/backups/jellyfin_postgres_backup_20250128_143022.dump
|
||||
[DEBUG] Executing external command: pg_dump -h localhost -p 5432 -U jellyfin -d jellyfin -F c -Z 6 -b -v -f "/data/backups/jellyfin_postgres_backup_20250128_143022.dump"
|
||||
[INFO] Successfully created PostgreSQL backup using external pg_dump at /data/backups/jellyfin_postgres_backup_20250128_143022.dump (15728640 bytes)
|
||||
[INFO] PostgreSQL local backup created using external pg_dump: /data/backups/jellyfin_postgres_backup_20250128_143022.dump
|
||||
```
|
||||
|
||||
### Successful Local Restore:
|
||||
```
|
||||
[INFO] Starting PostgreSQL restore using external pg_restore tool from /data/backups/jellyfin_postgres_backup_20250128_143022.dump
|
||||
[INFO] Successfully restored PostgreSQL backup using external pg_restore from /data/backups/jellyfin_postgres_backup_20250128_143022.dump
|
||||
[INFO] PostgreSQL local backup restored using external pg_restore from: /data/backups/jellyfin_postgres_backup_20250128_143022.dump
|
||||
```
|
||||
|
||||
### Successful Local Delete:
|
||||
```
|
||||
[INFO] Deleted local PostgreSQL backup created by external pg_dump: /data/backups/jellyfin_postgres_backup_20250128_143022.dump
|
||||
```
|
||||
|
||||
### Remote Database (Backups Disabled):
|
||||
```
|
||||
[INFO] PostgreSQL database is on remote server (db.example.com). Backup operations via external pg_dump/pg_restore tools are disabled
|
||||
[WARN] Fast backup is not implemented for PostgreSQL on a remote server. Use external pg_dump command manually for proper backups.
|
||||
```
|
||||
|
||||
### Error: External Tool Not Found:
|
||||
```
|
||||
[ERROR] External pg_dump executable not found. Please configure the path in database.xml or ensure PostgreSQL client tools are installed and in the system PATH.
|
||||
```
|
||||
|
||||
## Benefits of Updated Messaging
|
||||
|
||||
1. **Clarity**: Users understand that these are external processes, not built-in functionality
|
||||
2. **Troubleshooting**: Makes it clear that PostgreSQL client tools must be installed
|
||||
3. **Expectations**: Sets proper expectations about what the system is doing
|
||||
4. **Documentation**: Helps users understand the requirement for external dependencies
|
||||
5. **Transparency**: Makes the technical implementation more transparent
|
||||
|
||||
## Technical Details
|
||||
|
||||
- **Process Execution**: `System.Diagnostics.Process.Start()` is used to launch pg_dump/pg_restore
|
||||
- **Environment Variables**: `PGPASSWORD` is set in the process environment for authentication
|
||||
- **Standard Output/Error**: Captured for logging and error handling
|
||||
- **Working Directory**: Backup files are created in the Jellyfin data directory
|
||||
- **Timeout Handling**: Configurable timeout prevents hung processes
|
||||
|
||||
## For Users
|
||||
|
||||
These updated messages help users understand that:
|
||||
1. Jellyfin requires PostgreSQL client tools to be installed
|
||||
2. The backup functionality calls out to external commands
|
||||
3. Path configuration in `database.xml` points to actual executables
|
||||
4. Error messages about missing executables mean the tools need to be installed
|
||||
|
||||
## For Developers
|
||||
|
||||
The updated logging makes it clear:
|
||||
1. We're using process execution, not a library
|
||||
2. External dependencies are required
|
||||
3. Configuration affects external tool execution
|
||||
4. Debugging should include checking if tools are in PATH or configured correctly
|
||||
Reference in New Issue
Block a user