linux_patch_api/BUILD_PACKAGES.md

Linux Patch API - Package Build Guide

This document provides comprehensive instructions for building production-ready packages for the Linux Patch API across all supported platforms: Debian/Ubuntu (.deb), RHEL/CentOS/Fedora (.rpm), Arch Linux (.pkg.tar.zst), and Alpine Linux (.apk).

Prerequisites

For Debian Package Building

# Install required tools
apt-get update
apt-get install -y \
    cargo \
    rustc \
    debhelper \
    pkg-config \
    libsystemd-dev \
    dpkg-dev \
    fakeroot

For RPM Package Building

# Install required tools (RHEL/CentOS/Fedora)
dnf install -y \
    cargo \
    rust \
    rpm-build \
    rpmdevtools \
    systemd-rpm-macros \
    pkgconfig \
    systemd-devel \
    gcc

# Or on Ubuntu/Debian for cross-building
apt-get install -y \
    cargo \
    rustc \
    rpm \
    rpmbuild \
    libsystemd-dev

Building Debian Package (.deb)

Quick Build

cd /a0/usr/projects/linux_patch_api

# Build release binary
cargo build --release --target x86_64-unknown-linux-gnu

# Build Debian package
dpkg-buildpackage -us -uc -b

# Package will be created in parent directory
# linux-patch-api_1.0.0-1_amd64.deb

Detailed Build Process

# 1. Ensure release binary exists
cargo build --release --target x86_64-unknown-linux-gnu

# 2. Verify debian/ directory structure
ls -la debian/
# Should contain: control, rules, changelog, compat, install, conffiles, copyright
# And maintainer scripts: preinst, postinst, prerm, postrm

# 3. Build the package
dpkg-buildpackage -us -uc -b

# 4. Verify package contents
dpkg-deb --contents ../linux-patch-api_1.0.0-1_amd64.deb

# 5. Verify package info
dpkg-deb --info ../linux-patch-api_1.0.0-1_amd64.deb

# 6. Lint the package (optional but recommended)
lintian ../linux-patch-api_1.0.0-1_amd64.deb

Installation Test

# Install the package
dpkg -i linux-patch-api_1.0.0-1_amd64.deb

# Verify installation
systemctl status linux-patch-api
linux-patch-api --version

# Check installed files
dpkg -L linux-patch-api

# Remove package (keeping configs)
dpkg -r linux-patch-api

# Purge package (removing all configs)
dpkg -P linux-patch-api

Building RPM Package (.rpm)

Quick Build

cd /a0/usr/projects/linux_patch_api

# Build release binary
cargo build --release --target x86_64-unknown-linux-gnu

# Build RPM package
rpmbuild -ba linux-patch-api.spec

# Package will be created in ~/rpmbuild/RPMS/

Detailed Build Process

# 1. Set up RPM build environment
rpmdev-setuptree

# 2. Copy spec file to SPECS directory
cp linux-patch-api.spec ~/rpmbuild/SPECS/

# 3. Copy source tarball to SOURCES directory
# Create source tarball
tar -czvf linux-patch-api-1.0.0.tar.gz \
    --exclude=target \
    --exclude=.git \
    --exclude=debian \
    --exclude=*.deb \
    --exclude=*.rpm \
    .

mv linux-patch-api-1.0.0.tar.gz ~/rpmbuild/SOURCES/

# 4. Build the RPM
rpmbuild -ba ~/rpmbuild/SPECS/linux-patch-api.spec

# 5. Verify RPM contents
rpm -qlp ~/rpmbuild/RPMS/x86_64/linux-patch-api-1.0.0-1.el9.x86_64.rpm

# 6. Verify RPM info
rpm -qip ~/rpmbuild/RPMS/x86_64/linux-patch-api-1.0.0-1.el9.x86_64.rpm

# 7. Lint the spec file (optional but recommended)
rpmlint ~/rpmbuild/SPECS/linux-patch-api.spec

Installation Test

# Install the RPM
rpm -ivh ~/rpmbuild/RPMS/x86_64/linux-patch-api-1.0.0-1.el9.x86_64.rpm

# Or using dnf/yum
dnf install ~/rpmbuild/RPMS/x86_64/linux-patch-api-1.0.0-1.el9.x86_64.rpm

# Verify installation
systemctl status linux-patch-api
linux-patch-api --version

# List installed files
rpm -ql linux-patch-api

# Remove package
rpm -e linux-patch-api

Building Arch Package (.pkg.tar.zst)

Quick Build

cd /path/to/linux_patch_api

# Build release binary
cargo build --release

# Build Arch package
chmod +x build-arch.sh
SKIP_CARGO_BUILD=1 ./build-arch.sh

# Package will be created in releases/
ls -la releases/*.pkg.tar.zst

Detailed Build Process

# 1. Install build dependencies (Arch Linux)
sudo pacman -Syu --noconfirm rust cargo systemd git base-devel gcc

# 2. Build release binary
cargo build --release

# 3. Run build script
chmod +x build-arch.sh
./build-arch.sh

# 4. Verify package contents
bsdtar -tf releases/linux-patch-api-*.pkg.tar.zst

# 5. Verify package info
pacman -Qi releases/linux-patch-api-*.pkg.tar.zst

Install Script Hooks

The Arch package includes an .install file (configs/linux-patch-api.install) that runs automatically on install:

• post_install: Creates directories, copies example configs, enables systemd service
• post_upgrade: Reloads systemd daemon
• pre_remove: Stops and disables service
• post_remove: Cleans up empty directories

Installation Test

# Install the package
sudo pacman -U ./releases/linux-patch-api-*.pkg.tar.zst

# Verify installation
systemctl status linux-patch-api
linux-patch-api --version

# Check installed files
pacman -Ql linux-patch-api

# Verify config files exist
ls -la /etc/linux_patch_api/

# Remove package
sudo pacman -R linux-patch-api

Note: The build script creates a builduser for makepkg when running as root (typical in CI environments). The .install hook handles directory creation, config copying, and service enablement.

Building Alpine Package (.apk)

Quick Build

cd /path/to/linux_patch_api

# Build release binary (MUSL target for Alpine)
cargo build --release --target x86_64-unknown-linux-musl

# Build Alpine package
chmod +x build-alpine.sh
SKIP_CARGO_BUILD=1 ./build-alpine.sh

# Package will be created in releases/
ls -la releases/*.apk

Detailed Build Process

# 1. Install build dependencies (Alpine Linux)
apk add --no-cache alpine-sdk rust cargo openssl openssl-dev elogind-dev musl-dev abuild gcc

# 2. Add Rust MUSL target
rustup target add x86_64-unknown-linux-musl

# 3. Build release binary
cargo build --release --target x86_64-unknown-linux-musl

# 4. Run build script
chmod +x build-alpine.sh
./build-alpine.sh

# 5. Verify package contents
apk verify releases/*.apk

# 6. List package contents
tar -tzf releases/*.apk

Install Script Hooks

The Alpine package includes an install script (configs/linux-patch-api.apk-install) that runs automatically on install:

• pre_install: Creates directories, sets ownership and permissions
• post_install: Copies example configs, adds service to default runlevel
• pre_deinstall: Stops and removes service from runlevel
• post_deinstall: Cleans up empty directories

Installation Test

# Install the package
sudo apk add --allow-unstable ./releases/linux-patch-api-*.apk

# Verify installation
rc-service linux-patch-api status
linux-patch-api --version

# Check installed files
apk info -L linux-patch-api

# Verify config files exist
ls -la /etc/linux_patch_api/

# Remove package
sudo apk del linux-patch-api

Important: Alpine uses OpenRC instead of systemd. Key differences:

• Start service: rc-service linux-patch-api start
• Stop service: rc-service linux-patch-api stop
• Check status: rc-service linux-patch-api status
• Service init script: /etc/init.d/linux-patch-api
• The abuild tool generates signing keys automatically for CI builds

Using the Interactive Installer

For manual deployment without package managers:

# Ensure binary is built
cargo build --release --target x86_64-unknown-linux-gnu

# Run installer (must be root)
sudo ./install.sh

The installer will:

1. Detect operating system
2. Check prerequisites (systemd, binary)
3. Create system user and group
4. Create directory structure
5. Install binary and configuration files
6. Install systemd service
7. Optionally generate self-signed certificates
8. Optionally enable and start the service

Package Contents

Installed Files

Path	Description	Permissions
/usr/bin/linux-patch-api	Main binary	755
/lib/systemd/system/linux-patch-api.service	Systemd service unit	644
/etc/linux_patch_api/config.yaml	Main configuration	640
/etc/linux_patch_api/whitelist.yaml	IP whitelist	640
/etc/linux_patch_api/certs/	TLS certificates directory	750
/var/lib/linux_patch_api/	Data directory	755
/var/log/linux_patch_api/	Log directory	755

Service Account

Property	Value
User	root
Group	root
Home	/var/lib/linux_patch_api
Shell	N/A (systemd service)
Type	Runs as root (required for package management)

Note: The service runs as root because package management operations (apt, dnf, apk, pacman) require root privileges. Security is provided by mTLS + IP whitelist, not process isolation.

Supported Distributions

Debian Package (.deb)

Distribution	Versions	Status
Debian	11 (Bullseye), 12 (Bookworm)	✅ Supported
Ubuntu	20.04 LTS (Focal)	✅ Supported
Ubuntu	22.04 LTS (Jammy)	✅ Supported
Ubuntu	24.04 LTS (Noble)	✅ Supported

RPM Package (.rpm)

Distribution	Versions	Status
RHEL	8, 9	✅ Supported
CentOS	8, 9	✅ Supported
Fedora	38+	✅ Supported
AlmaLinux	8, 9	✅ Supported
Rocky Linux	8, 9	✅ Supported

Arch Package (.pkg.tar.zst)

Distribution	Versions	Status
Arch Linux	Rolling	✅ Supported
Manjaro	Rolling	✅ Supported

Alpine Package (.apk)

Distribution	Versions	Status
Alpine Linux	3.18+	✅ Supported

Troubleshooting

Debian Package Issues

Error: dh_auto_install: error: ...

# Ensure release binary exists
ls -la target/x86_64-unknown-linux-gnu/release/linux-patch-api

# Rebuild if missing
cargo build --release --target x86_64-unknown-linux-gnu

Error: missing build-dependency

# Install missing dependencies
apt-get install -y libsystemd-dev pkg-config

RPM Package Issues

Error: RPMS not found

# Check build output
ls -la ~/rpmbuild/RPMS/x86_64/

# Check for build errors
cat ~/rpmbuild/BUILDROOT/*/var/log/rpmbuild.log

Error: missing BuildRequires

# Install development packages
dnf install -y systemd-devel pkgconfig

Arch Package Issues

Error: makepkg: cannot run as root

# The build script handles this automatically by creating builduser
# If running manually:
useradd -m builduser
su - builduser -c "cd /path/to/repo && makepkg -f --noconfirm"

Error: install script not found

# Ensure linux-patch-api.install is in the same directory as PKGBUILD
ls -la configs/linux-patch-api.install
# The build script copies it automatically

Error: Permission denied on config files

# Verify ownership is root:root
ls -la /etc/linux_patch_api/
# Fix if needed:
sudo chown -R root:root /etc/linux_patch_api/
sudo chmod 750 /etc/linux_patch_api /etc/linux_patch_api/certs

Alpine Package Issues

Error: abuild: UNTRUSTED signature

# The build script handles key generation automatically
# If running manually:
abuild-keygen -a -n
cp /root/.abuild/*.rsa.pub /etc/apk/keys/

Error: apk add: ERROR: failed to create directory

# Verify the install script ran correctly
ls -la /etc/linux_patch_api/
ls -la /var/lib/linux_patch_api/
# Manually create if needed:
sudo mkdir -p /etc/linux_patch_api/certs /var/lib/linux_patch_api /var/log/linux_patch_api

Error: rc-service: service not found

# Verify the init script exists
ls -la /etc/init.d/linux-patch-api
# Re-add to default runlevel
sudo rc-update add linux-patch-api default

Service Issues

Service fails to start (systemd):

# Check service status
systemctl status linux-patch-api

# View logs
journalctl -u linux-patch-api -f

# Check configuration
linux-patch-api --config /etc/linux_patch_api/config.yaml --check

# Verify certificates
ls -la /etc/linux_patch_api/certs/

Service fails to start (OpenRC/Alpine):

# Check service status
rc-service linux-patch-api status

# View logs
cat /var/log/linux_patch_api/linux-patch-api.log
cat /var/log/linux_patch_api/linux-patch-api.err

# Check configuration
linux-patch-api --config /etc/linux_patch_api/config.yaml --check

# Verify certificates
ls -la /etc/linux_patch_api/certs/

CI/CD Integration

GitHub Actions Example

name: Build Packages

on:
  release:
    types: [published]

jobs:
  build-deb:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y cargo debhelper pkg-config libsystemd-dev
      
      - name: Build release
        run: cargo build --release
      
      - name: Build Debian package
        run: dpkg-buildpackage -us -uc -b
      
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: linux-patch-api-deb
          path: ../linux-patch-api_*.deb

  build-rpm:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y cargo rpm rpmbuild
      
      - name: Set up RPM environment
        run: rpmdev-setuptree
      
      - name: Build release
        run: cargo build --release
      
      - name: Build RPM package
        run: rpmbuild -ba linux-patch-api.spec
      
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: linux-patch-api-rpm
          path: ~/rpmbuild/RPMS/x86_64/*.rpm

Version Management

Updating Version for New Release

1. Update Cargo.toml:

   [package]
   version = "1.0.1"  # Increment version
   

2. Update debian/changelog:

   dch -v 1.0.1-1 "Release notes here"
   

3. Update RPM spec:

   Version:        1.0.1
   Release:        1%{?dist}
   

4. Update ROADMAP.md:

   • Mark previous version complete
   • Add new version to changelog

Security Considerations

• Packages are signed with maintainer GPG key for production deployments
• All maintainer scripts run with set -e for fail-fast behavior
• Configuration files are marked as conffiles to preserve user modifications
• Service runs as root (required for package management operations)
• Directory permissions follow principle of least privilege
• TLS certificates should be replaced with CA-signed certs in production

Support

For issues or questions:

• Review logs: journalctl -u linux-patch-api -f
• Check documentation: /usr/share/doc/linux-patch-api/
• Report issues: https://gitea.moon-dragon.us/echo/linux_patch_api/issues