Add SQL query patterns documentation and Linux package build scripts

- Created `TV_SHOWS_SQL_QUERY_PATTERNS.md` to document SQL query patterns for TV shows, including performance issues and missing indexes. - Added `README.md` for Linux package building, detailing steps for creating Debian and Red Hat packages. - Implemented build scripts for Debian and Red Hat, including service files and post-installation hooks. - Added necessary scripts for managing Jellyfin service lifecycle on both Debian and Red Hat systems. - Included package specifications and installation instructions for both distributions.
2026-07-14 10:32:56 -04:00
parent e51d3577ce
commit 8914f4dce9
29 changed files with 4123 additions and 31 deletions
@@ -0,0 +1,327 @@
+# Debian and Red Hat Package Building - Complete Summary
+
+## Overview
+
+Your Jellyfin project can now build packages for both Debian and Red Hat-based distributions using a single publishing configuration. Both distributions use:
+
+- **Runtime**: `linux-x64`
+- **Configuration**: `Release`  
+- **Self-contained**: `true` (includes .NET runtime)
+
+The publishing step is identical; only the packaging format differs (`.deb` vs `.rpm`).
+
+## Documentation Structure
+
+### 📖 Main Documentation
+**File**: [LINUX_PACKAGE_BUILD_GUIDE.md](LINUX_PACKAGE_BUILD_GUIDE.md)
+
+Complete reference covering:
+- Common publishing setup
+- Debian package building (FPM method and manual dpkg-deb method)
+- Red Hat package building (FPM method and native rpmbuild method)
+- Installation and verification procedures
+- Testing in Docker containers
+
+### ⚡ Quick Reference
+**File**: [LINUX_PACKAGE_BUILD_QUICK_REFERENCE.md](LINUX_PACKAGE_BUILD_QUICK_REFERENCE.md)
+
+Quick commands for:
+- One-command builds
+- Prerequisites
+- Installation variations
+- Key directories and systemd commands
+- Troubleshooting table
+
+### 🛠️ Build Scripts
+**Location**: `scripts/`
+
+1. **build-linux-packages.sh** - Main automated build script
+   - Checks prerequisites
+   - Publishes application
+   - Creates both Debian and Red Hat packages
+   - Colored output with progress indicators
+
+2. **jellyfin.spec** - Red Hat SPEC file template
+   - For native rpmbuild method
+   - Contains hooks and metadata
+
+3. **debian/** - Debian-specific files
+   - postinst.sh - Post-install hook
+   - prerm.sh - Pre-remove hook
+   - postrm.sh - Post-remove hook
+   - jellyfin.service - Systemd service file
+
+4. **redhat/** - Red Hat-specific files
+   - post.sh - Post-install hook
+   - preun.sh - Pre-uninstall hook
+   - postun.sh - Post-uninstall hook
+   - jellyfin.service - Systemd service file
+
+5. **scripts/README.md** - Build script documentation
+   - Directory structure
+   - Prerequisites and installation
+   - Package specifications
+   - Hooks and lifecycle
+   - Customization options
+
+## Quick Start
+
+### Prerequisites (One-Time Setup)
+
+**Debian/Ubuntu:**
+```bash
+sudo apt-get install ruby-dev
+sudo gem install fpm
+```
+
+**Red Hat/CentOS/Fedora:**
+```bash
+sudo dnf install ruby-devel
+sudo gem install fpm
+```
+
+### Build Both Packages
+
+```bash
+cd /home/wjones/projects/pgsql-jellyfin
+chmod +x build-linux-packages.sh
+./build-linux-packages.sh
+```
+
+Output: `build/packages/`
+- `jellyfin-11.0.0-amd64.deb`
+- `jellyfin-11.0.0-1.x86_64.rpm`
+
+### Build Specific Distribution
+
+```bash
+./build-linux-packages.sh --deb-only   # Debian only
+./build-linux-packages.sh --rpm-only   # Red Hat only
+./build-linux-packages.sh --version 12.0.0  # Custom version
+```
+
+### Install Package
+
+**Debian:**
+```bash
+sudo dpkg -i build/packages/jellyfin-11.0.0-amd64.deb
+sudo apt-get install -f  # Fix dependencies if needed
+sudo systemctl start jellyfin
+```
+
+**Red Hat:**
+```bash
+sudo dnf install build/packages/jellyfin-11.0.0-1.x86_64.rpm
+sudo systemctl start jellyfin
+```
+
+## Build Process Flow
+
+```
+┌─────────────────────────────────────────┐
+│ User runs: ./build-linux-packages.sh   │
+└────────────┬────────────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────────────┐
+│ Check Prerequisites                      │
+│ • .NET SDK                               │
+│ • FPM (package manager)                  │
+└────────────┬────────────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────────────┐
+│ Publish Application (linux-x64)          │
+│ • Restore dependencies                   │
+│ • Build (Release config)                 │
+│ • Self-contained publish                 │
+│ → /tmp/jellyfin-publish-{pid}           │
+└────────────┬────────────────────────────┘
+             │
+     ┌───────┴────────┐
+     │                │
+     ▼                ▼
+┌──────────────┐  ┌──────────────┐
+│ Build Debian │  │ Build Red Hat│
+│   Package    │  │   Package    │
+│              │  │              │
+│ FPM:         │  │ FPM:         │
+│ .deb format  │  │ .rpm format  │
+└──────┬───────┘  └──────┬───────┘
+       │                 │
+       └────────┬────────┘
+                ▼
+┌─────────────────────────────────────────┐
+│ Output to: build/packages/               │
+│ • jellyfin-VERSION-amd64.deb            │
+│ • jellyfin-VERSION-1.x86_64.rpm         │
+└─────────────────────────────────────────┘
+```
+
+## Key Features
+
+### Package Metadata
+- **Version**: Automatically extracted from `SharedVersion.cs`
+- **Architecture**: x86_64 (64-bit)
+- **Dependencies**:
+  - Debian: libssl3, libicu72, libfontconfig1
+  - Red Hat: openssl-libs, libicu, fontconfig
+
+### Installation Hooks
+- **Post-install**: Creates user/group, sets permissions, enables service
+- **Pre-remove**: Stops service
+- **Post-remove**: Removes user/group
+
+### Service File
+- **Type**: Simple systemd service
+- **Auto-restart**: On failure (5s delay)
+- **Resource limits**: 4GB max memory, 65k file descriptors
+- **Directories**:
+  - Config: `/var/lib/jellyfin`
+  - Logs: `/var/log/jellyfin`
+  - Cache: `/var/cache/jellyfin`
+
+### User Management
+- **Username**: `jellyfin` (system user, no shell)
+- **Home**: `/var/lib/jellyfin`
+- **Created automatically** during package installation
+- **Removed automatically** during package removal
+
+## Testing
+
+### Manual Testing
+
+```bash
+# Extract and inspect package contents
+dpkg -c jellyfin-11.0.0-amd64.deb | head -20
+rpm -qpl jellyfin-11.0.0-1.x86_64.rpm | head -20
+
+# Verify hooks
+dpkg-deb -e jellyfin-11.0.0-amd64.deb /tmp/control
+rpm -qp --scripts jellyfin-11.0.0-1.x86_64.rpm
+```
+
+### Docker Testing
+
+```bash
+# Test on Debian
+docker run --rm -it -v $(pwd)/build/packages:/pkg debian:bookworm \
+  bash -c "dpkg -i /pkg/jellyfin-11.0.0-amd64.deb && systemctl status jellyfin"
+
+# Test on Fedora
+docker run --rm -it -v $(pwd)/build/packages:/pkg fedora:latest \
+  bash -c "dnf install -y /pkg/jellyfin-11.0.0-1.x86_64.rpm && systemctl status jellyfin"
+
+# Test on Rocky Linux
+docker run --rm -it -v $(pwd)/build/packages:/pkg rockylinux:9 \
+  bash -c "dnf install -y /pkg/jellyfin-11.0.0-1.x86_64.rpm && systemctl status jellyfin"
+```
+
+## Troubleshooting
+
+### FPM Installation Issues
+
+```bash
+# Ensure Ruby development headers are installed
+sudo apt-get install ruby-dev        # Debian/Ubuntu
+sudo dnf install ruby-devel          # Red Hat
+
+# Then install FPM
+sudo gem install fpm
+```
+
+### Build Script Permissions
+
+```bash
+chmod +x build-linux-packages.sh
+chmod +x scripts/debian/postinst.sh scripts/debian/prerm.sh scripts/debian/postrm.sh
+chmod +x scripts/redhat/post.sh scripts/redhat/preun.sh scripts/redhat/postun.sh
+```
+
+### Service Won't Start
+
+Check logs for errors:
+```bash
+sudo journalctl -u jellyfin -n 50
+sudo journalctl -u jellyfin -f  # Follow logs
+```
+
+Check permissions:
+```bash
+ls -la /opt/jellyfin
+ls -la /var/lib/jellyfin
+```
+
+### Dependency Resolution
+
+**Debian**: If dpkg reports missing dependencies:
+```bash
+sudo apt-get install -f
+```
+
+**Red Hat**: dnf resolves dependencies automatically
+
+## No Red Hat System Required
+
+The documentation and scripts can be created and tested on any Linux system:
+
+- ✅ Debian/Ubuntu systems can create `.rpm` packages using FPM
+- ✅ Red Hat systems can create `.deb` packages using FPM
+- ✅ Cross-distribution testing via Docker
+- ✅ Single .NET publishing configuration works for both
+
+To actually run the packages on their respective distributions, you can:
+1. Test locally using Docker containers
+2. Deploy to VMs or servers running those distributions
+3. Use CI/CD pipeline to test on actual systems
+
+## File Manifest
+
+```
+/home/wjones/projects/pgsql-jellyfin/
+├── docs/
+│   ├── LINUX_PACKAGE_BUILD_GUIDE.md (Complete reference)
+│   ├── LINUX_PACKAGE_BUILD_QUICK_REFERENCE.md (Quick commands)
+│   └── PACKAGE_BUILDING_SUMMARY.md (This file)
+│
+├── scripts/
+│   ├── README.md (Build scripts documentation)
+│   ├── build-linux-packages.sh (Main build script)
+│   ├── jellyfin.spec (Red Hat SPEC template)
+│   ├── debian/
+│   │   ├── postinst.sh
+│   │   ├── prerm.sh
+│   │   ├── postrm.sh
+│   │   └── jellyfin.service
+│   └── redhat/
+│       ├── post.sh
+│       ├── preun.sh
+│       ├── postun.sh
+│       └── jellyfin.service
+│
+└── build/
+    └── packages/ (Output location)
+        ├── jellyfin-11.0.0-amd64.deb
+        └── jellyfin-11.0.0-1.x86_64.rpm
+```
+
+## Next Steps
+
+1. ✅ **Read Documentation**
+   - Start with [LINUX_PACKAGE_BUILD_QUICK_REFERENCE.md](LINUX_PACKAGE_BUILD_QUICK_REFERENCE.md)
+   - Reference [LINUX_PACKAGE_BUILD_GUIDE.md](LINUX_PACKAGE_BUILD_GUIDE.md) for details
+
+2. ✅ **Install Prerequisites**
+   - `sudo apt-get install ruby-dev && sudo gem install fpm` (or Red Hat equivalent)
+
+3. ✅ **Build Packages**
+   - `./build-linux-packages.sh`
+
+4. ✅ **Test Installation**
+   - Test locally or in Docker containers
+   - Verify service starts: `sudo systemctl status jellyfin`
+
+5. ✅ **Deploy**
+   - Copy `.deb` to Debian systems
+   - Copy `.rpm` to Red Hat systems
+   - Install and verify