pgsql-jellyfin/docs/PACKAGE_BUILDING_SUMMARY.md

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

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

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:

sudo apt-get install ruby-dev
sudo gem install fpm

Red Hat/CentOS/Fedora:

sudo dnf install ruby-devel
sudo gem install fpm

Build Both Packages

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

./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:

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:

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

# 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

# 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

# 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

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:

sudo journalctl -u jellyfin -n 50
sudo journalctl -u jellyfin -f  # Follow logs

Check permissions:

ls -la /opt/jellyfin
ls -la /var/lib/jellyfin

Dependency Resolution

Debian: If dpkg reports missing dependencies:

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
   • Reference 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