Add Debian packaging and update Forgejo workflow

- Add complete Debian packaging configuration (debian/ directory) - Create build-deb.sh script for building packages - Update Forgejo workflow to build and upload .deb artifacts - Add comprehensive version naming for both binary and Debian artifacts - Update .gitignore to exclude build artifacts and packaging files - Add PACKAGING.md documentation - Add test-deb.sh for testing package installation
2025-08-10 11:30:19 -07:00 · 2025-08-10 11:30:19 -07:00 · 73b43239e9
commit 73b43239e9
parent ff974a9d4a
19 changed files with 705 additions and 21 deletions
--- a/.forgejo/workflows/build-artifacts.yml
+++ b/.forgejo/workflows/build-artifacts.yml
@ -124,9 +124,9 @@ jobs:
          git clone https://git.raines.xyz/robojerk/deb-bootupd.git /tmp/deb-bootupd
          cd /tmp/deb-bootupd
          
-          echo "Repository: $(git remote get-url origin)"
-          echo "Branch: $(git branch --show-current)"
-          echo "Commit: $(git rev-parse --short HEAD)"
+                          echo "Repository: ${GITHUB_REPOSITORY:-$(git remote get-url origin 2>/dev/null || echo "unknown")}"
+                          echo "Branch: ${GITHUB_REF_NAME:-$(git branch --show-current 2>/dev/null || echo "unknown")}"
+                          echo "Commit: ${GITHUB_SHA:-$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")}"
          
          # Verify Rust version meets requirements (need 1.84.1+)
          RUST_VERSION=$(rustc --version | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+' | head -1)
@ -254,6 +254,49 @@ jobs:
          ls -la artifacts/
          ls -la *.zip

+      - name: Build Debian package
+        run: |
+          cd /tmp/deb-bootupd
+          
+          echo "=== BUILDING DEBIAN PACKAGE ==="
+          
+          # Install Debian packaging dependencies
+          apt update -y
+          apt install -y devscripts dh-cargo build-essential
+          
+          # Verify debian packaging files
+          echo "Debian packaging files:"
+          ls -la debian/
+          
+          # Build the Debian package
+          echo "Building Debian package..."
+          ./build-deb.sh
+          
+          # Check what was built
+          echo "Package build results:"
+          ls -la ../*.deb ../*.buildinfo ../*.changes ../*.dsc 2>/dev/null || echo "No package files found in parent directory"
+          
+          # Create debian artifacts directory
+          mkdir -p debian-artifacts
+          
+          # Copy all package files
+          cp ../*.deb ../*.buildinfo ../*.changes ../*.dsc debian-artifacts/ 2>/dev/null || echo "No package files to copy"
+          
+          # Create debian package archive
+          cd debian-artifacts
+          if [ -n "$(ls -A .)" ]; then
+            # Create versioned artifact name matching the binary artifact pattern
+            VERSIONED_DEBIAN_ARTIFACT="deb-bootupd-debian-${BOOTUPD_VERSION}-${FORK_VERSION}-${TARGET_PLATFORM}-$(git rev-parse --short HEAD).zip"
+            zip -r "../$VERSIONED_DEBIAN_ARTIFACT" .
+            echo "✅ Debian package artifacts created"
+            echo "📦 Versioned Debian artifact: $VERSIONED_DEBIAN_ARTIFACT"
+            ls -la ../*.zip
+          else
+            echo "❌ No Debian package files found"
+            exit 1
+          fi
+          cd ..
+
      - name: Upload artifacts to Forgejo
        env:
          USER: robojerk
@ -299,15 +342,55 @@ jobs:
              "$upload_url" 2>&1
            exit 1
          fi
+          
+          # Upload Debian package
+          echo "Uploading Debian package to Forgejo Package Registry..."
+          
+          VERSIONED_DEBIAN_ARTIFACT="deb-bootupd-debian-${BOOTUPD_VERSION}-${FORK_VERSION}-${TARGET_PLATFORM}-$(git rev-parse --short HEAD).zip"
+          if [ -f "$VERSIONED_DEBIAN_ARTIFACT" ]; then
+            # Create Debian package path
+            debian_path="api/packages/robojerk/generic/deb-bootupd-debian/${BOOTUPD_VERSION}-${FORK_VERSION}-${TARGET_PLATFORM}"
+            debian_upload_url="https://${BASE_URL}/${debian_path}/${VERSIONED_DEBIAN_ARTIFACT}"
+            
+            echo "Debian package upload URL: $debian_upload_url"
+            echo "Debian package path: $debian_path"
+            
+            # Upload Debian package
+            debian_http_code=$(curl -s -o /dev/null -w "%{http_code}" \
+              --user "${USER}:${TOKEN}" \
+              --upload-file "$VERSIONED_DEBIAN_ARTIFACT" \
+              "$debian_upload_url")
+            
+            echo "Debian package HTTP Response Code: $debian_http_code"
+            
+            if [ "$debian_http_code" = "201" ]; then
+              echo "✅ Debian package uploaded successfully to Forgejo Package Registry"
+              echo "📦 Debian package available at: https://${BASE_URL}/robojerk/-/packages/generic/deb-bootupd-debian"
+            elif [ "$debian_http_code" = "409" ]; then
+              echo "➡️ INFO: Debian package already exists (HTTP 409 Conflict)"
+            else
+              echo "❌ Debian package upload failed with HTTP $debian_http_code"
+              # Show verbose output for debugging
+              curl -v -i --user "${USER}:${TOKEN}" \
+                --upload-file "$VERSIONED_DEBIAN_ARTIFACT" \
+                "$debian_upload_url" 2>&1
+              exit 1
+            fi
+          else
+            echo "❌ Debian package artifact not found: $VERSIONED_DEBIAN_ARTIFACT"
+            exit 1
+          fi

      - name: Create release assets
        run: |
          cd /tmp/deb-bootupd
          
          VERSIONED_ARTIFACT="bootupd-${BOOTUPD_VERSION}-${FORK_VERSION}-${TARGET_PLATFORM}-$(git rev-parse --short HEAD).zip"
+          VERSIONED_DEBIAN_ARTIFACT="deb-bootupd-debian-${BOOTUPD_VERSION}-${FORK_VERSION}-${TARGET_PLATFORM}-$(git rev-parse --short HEAD).zip"
          
          mkdir -p release-assets
          cp "$VERSIONED_ARTIFACT" release-assets/ 2>/dev/null || echo "No versioned artifact found"
+          cp "$VERSIONED_DEBIAN_ARTIFACT" release-assets/ 2>/dev/null || echo "No Debian artifact found"
          
          # Create a summary file
          cat > release-assets/BUILD_SUMMARY.txt << EOF
@ -320,8 +403,8 @@ jobs:
          Debian Version: ${DEBIAN_VERSION}
          Container Image: rust:1.89-slim-trixie
          Rust Version: $(rustc --version)
-          Git Commit: $(git rev-parse --short HEAD)
-          Git Branch: $(git branch --show-current)
+          Git Commit: ${GITHUB_SHA:-$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")}
+          Git Branch: ${GITHUB_REF_NAME:-$(git branch --show-current 2>/dev/null || echo "unknown")}
          
          Built Artifacts:
          - Rust binary (release mode): bootupd
@ -329,10 +412,17 @@ jobs:
          - Archive Size: $(ls -lh "$VERSIONED_ARTIFACT" | awk '{print $5}')
          - Compression: 77% (from binary to archive)
          
-          Artifact Archive: $VERSIONED_ARTIFACT
+          Debian Package:
+          - Package Archive: $VERSIONED_DEBIAN_ARTIFACT
+          - Package Size: $(ls -lh "$VERSIONED_DEBIAN_ARTIFACT" | awk '{print $5}')
          
-          Package Registry:
-          https://git.raines.xyz/robojerk/-/packages/generic/deb-bootupd
+          Artifact Archives:
+          - Binary: $VERSIONED_ARTIFACT
+          - Debian: $VERSIONED_DEBIAN_ARTIFACT
+          
+          Package Registries:
+          - Binary: https://git.raines.xyz/robojerk/-/packages/generic/deb-bootupd
+          - Debian: https://git.raines.xyz/robojerk/-/packages/generic/deb-bootupd-debian
          EOF
          
          echo "Release assets created:"
@ -341,21 +431,25 @@ jobs:
      - name: Success Summary
        run: |
          VERSIONED_ARTIFACT="bootupd-${BOOTUPD_VERSION}-${FORK_VERSION}-${TARGET_PLATFORM}-$(git rev-parse --short HEAD).zip"
+          VERSIONED_DEBIAN_ARTIFACT="deb-bootupd-debian-${BOOTUPD_VERSION}-${FORK_VERSION}-${TARGET_PLATFORM}-$(git rev-parse --short HEAD).zip"
          
          echo "=== Build Summary ==="
          echo "✅ deb-bootupd compiled successfully in release mode"
          echo "✅ All tests passed"
          echo "✅ Code formatting and linting passed"
          echo "✅ Build artifacts created and uploaded to Forgejo"
+          echo "✅ Debian package built and uploaded to Forgejo"
          echo ""
-          echo "📦 Versioned Artifact: $VERSIONED_ARTIFACT"
+          echo "📦 Binary Artifact: $VERSIONED_ARTIFACT"
+          echo "📦 Debian Package: $VERSIONED_DEBIAN_ARTIFACT"
          echo "🎯 Package Structure: bootupd-${BOOTUPD_VERSION}-${FORK_VERSION}-${TARGET_PLATFORM}"
          echo ""
          echo "📦 Artifacts available at:"
-          echo "   https://git.raines.xyz/robojerk/-/packages/generic/deb-bootupd"
+          echo "   Binary: https://git.raines.xyz/robojerk/-/packages/generic/deb-bootupd"
+          echo "   Debian: https://git.raines.xyz/robojerk/-/packages/generic/deb-bootupd-debian"
          echo ""
          echo "🎯 Next steps:"
          echo "   - Verify artifacts appear in repository packages page"
          echo "   - Test binaries on Debian Trixie systems"
-          echo "   - Consider building .deb packages for distribution"
+          echo "   - Test Debian package installation on target systems"
          echo "   - Update version numbers for future releases"
--- a/.forgejo/workflows/simple-build.yml
+++ b/.forgejo/workflows/simple-build.yml
@ -122,9 +122,9 @@ jobs:
          git clone https://git.raines.xyz/robojerk/deb-bootupd.git /tmp/deb-bootupd
          cd /tmp/deb-bootupd
          
-          echo "Repository: $(git remote get-url origin)"
-          echo "Branch: $(git branch --show-current)"
-          echo "Commit: $(git rev-parse --short HEAD)"
+                          echo "Repository: ${GITHUB_REPOSITORY:-$(git remote get-url origin 2>/dev/null || echo "unknown")}"
+                echo "Branch: ${GITHUB_REF_NAME:-$(git branch --show-current 2>/dev/null || echo "unknown")}"
+                echo "Commit: ${GITHUB_SHA:-$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")}"
          
          # Verify Rust version meets requirements (need 1.84.1+)
          RUST_VERSION=$(rustc --version | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+' | head -1)
--- a/.gitignore
+++ b/.gitignore
@ -1,4 +1,42 @@
+# Rust build artifacts
 /target
+
+# Debian packaging artifacts
+debian/deb-bootupd/
+debian/files
+debian/*.debhelper
+debian/*.substvars
+debian/*.log
+debian/*.deb
+debian/*.buildinfo
+debian/*.changes
+debian/*.dsc
+debian/*.tar.*
+
+# Build artifacts
 fastbuild*.qcow2
 _kola_temp
 .cosa
+
+# Package build outputs
+*.deb
+*.buildinfo
+*.changes
+*.dsc
+*.tar.*
+
+# Temporary files
+*.tmp
+*.temp
+*~
+
+# IDE and editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS generated files
+.DS_Store
+Thumbs.db
--- a/PACKAGING.md
+++ b/PACKAGING.md
@ -0,0 +1,212 @@
+# 📦 Debian Packaging Guide for deb-bootupd
+
+This guide explains how to build, test, and distribute proper Debian packages for `deb-bootupd`.
+
+## **🏗️ Package Structure**
+
+Your Debian package now includes all required components:
+
+```
+debian/
+├── control          # Package metadata and dependencies
+├── rules            # Build instructions
+├── changelog        # Version history
+├── copyright        # License information
+├── install          # File installation mapping
+├── dirs             # Directory creation
+├── postinst         # Post-installation script
+├── prerm            # Pre-removal script
+└── postrm           # Post-removal script
+```
+
+## **🔨 Building the Package**
+
+### **Prerequisites**
+
+Install required build tools:
+
+```bash
+sudo apt-get update
+sudo apt-get install build-essential devscripts dh-cargo dh-systemd lintian
+```
+
+### **Quick Build**
+
+Use the automated build script:
+
+```bash
+./build-deb.sh
+```
+
+This will:
+1. Clean previous builds
+2. Build the Rust binary
+3. Create the Debian package
+4. Validate with lintian (if available)
+
+### **Manual Build**
+
+Or build manually:
+
+```bash
+# Clean previous builds
+rm -rf target/ debian/deb-bootupd/ *.deb *.changes *.buildinfo *.dsc
+
+# Build the package
+dpkg-buildpackage -b -uc -us
+```
+
+## **🧪 Testing the Package**
+
+### **Package Validation**
+
+Test the built package:
+
+```bash
+./test-deb.sh
+```
+
+This validates:
+- Package structure
+- File locations
+- Dependencies
+- Installation (dry run)
+
+### **Manual Testing**
+
+```bash
+# Check package info
+dpkg-deb -I ../deb-bootupd_*.deb
+
+# View package contents
+dpkg-deb -c ../deb-bootupd_*.deb
+
+# Test installation
+sudo dpkg -i ../deb-bootupd_*.deb
+sudo apt-get install -f  # Fix dependencies if needed
+```
+
+## **📋 Package Contents**
+
+Your package installs:
+
+- **Binary**: `/usr/libexec/bootupd` (multicall executable)
+- **Symlink**: `/usr/bin/bootupctl` → `/usr/libexec/bootupd`
+- **Documentation**: README, changelog, and version info
+- **No Services**: `bootupd` is NOT a daemon - it's a CLI tool
+
+## **🔧 Package Configuration**
+
+### **Dependencies**
+
+- **Build**: `rustc`, `cargo`, `dh-cargo`
+- **Runtime**: `efibootmgr`, `grub-common`, `ostree` (recommended)
+
+### **Multicall Binary Architecture**
+
+- **Main Binary**: `/usr/libexec/bootupd` (multicall binary)
+- **CLI Client**: `/usr/bin/bootupctl` → `/usr/libexec/bootupd` (symlink)
+- **Command Dispatch**: Based on argv[0] (how the binary is invoked)
+- **No Daemon**: `bootupd` is NOT a service - it's a CLI tool
+
+**How it works:**
+- When invoked as `bootupd` → Shows **backend commands** (`generate-update-metadata`, `install`)
+- When invoked as `bootupctl` → Shows **CLI commands** (`status`, `update`, `validate`, `adopt-and-update`)
+- The binary automatically detects which interface to show based on the command name used to invoke it
+
+## **📊 Quality Assurance**
+
+### **Lintian Checks**
+
+Run comprehensive validation:
+
+```bash
+lintian ../deb-bootupd_*.changes
+```
+
+### **Common Issues to Check**
+
+- [ ] Binary is executable
+- [ ] Symlinks are correct
+- [ ] Systemd files are present
+- [ ] Documentation is included
+- **Dependencies are accurate**
+- **Package follows Debian policy**
+
+## **🚀 Distribution**
+
+### **Local Installation**
+
+```bash
+sudo dpkg -i deb-bootupd_*.deb
+sudo apt-get install -f  # Fix dependencies
+```
+
+### **Repository Distribution**
+
+For distribution via APT repositories:
+
+1. **Sign the package**:
+   ```bash
+   dpkg-sig --sign builder deb-bootupd_*.deb
+   ```
+
+2. **Upload to repository**:
+   ```bash
+   reprepro -b /path/to/repo includedeb trixie deb-bootupd_*.deb
+   ```
+
+### **CI/CD Integration**
+
+Your Forgejo Actions workflow can now build `.deb` packages:
+
+```yaml
+- name: Build Debian Package
+  run: |
+    ./build-deb.sh
+    
+- name: Upload Package
+  uses: actions/upload-artifact@v3
+  with:
+    name: deb-bootupd-package
+    path: ../deb-bootupd_*.deb
+```
+
+## **🔍 Troubleshooting**
+
+### **Build Failures**
+
+- **Missing dependencies**: Install required build packages
+- **Rust compilation errors**: Check `Cargo.toml` and dependencies
+- **Permission errors**: Ensure scripts are executable
+
+### **Package Issues**
+
+- **Installation fails**: Check dependencies with `dpkg-deb -I`
+- **Service not starting**: Verify systemd files and permissions
+- **Binary not found**: Check file paths in `debian/install`
+
+### **Validation Errors**
+
+- **Lintian warnings**: Address policy violations
+- **Missing files**: Verify `debian/install` mapping
+- **Wrong permissions**: Check file modes in rules
+
+## **📚 Resources**
+
+- [Debian Packaging Guide](https://wiki.debian.org/HowToPackageForDebian)
+- [Debian Policy Manual](https://www.debian.org/doc/debian-policy/)
+- [dh-cargo Documentation](https://docs.rs/dh-cargo/)
+- [dh-systemd Documentation](https://manpages.debian.org/dh-systemd)
+
+## **🎯 Next Steps**
+
+1. **Test the package** on a clean Debian Trixie system
+2. **Validate with lintian** and fix any issues
+3. **Set up a package repository** for distribution
+4. **Integrate with CI/CD** for automated builds
+5. **Publish to Debian repositories** (if desired)
+
+---
+
+**Happy Packaging! 🎉**
--- a/build-deb.sh
+++ b/build-deb.sh
@ -0,0 +1,49 @@
+#!/bin/bash
+set -e
+
+# Build script for deb-bootupd Debian package
+# This script builds a proper .deb package following Debian packaging standards
+
+echo "🐳 Building deb-bootupd Debian package..."
+
+# Check if we're in the right directory
+if [ ! -f "Cargo.toml" ] || [ ! -d "debian" ]; then
+    echo "❌ Error: This script must be run from the deb-bootupd root directory"
+    exit 1
+fi
+
+# Check for required tools
+command -v dpkg-buildpackage >/dev/null 2>&1 || { echo "❌ Error: dpkg-buildpackage not found. Install build-essential and devscripts."; exit 1; }
+command -v lintian >/dev/null 2>&1 || { echo "⚠️  Warning: lintian not found. Install lintian for package validation."; }
+
+# Clean previous builds
+echo "🧹 Cleaning previous build artifacts..."
+rm -rf target/ debian/deb-bootupd/ *.deb *.changes *.buildinfo *.dsc
+
+# Build the package
+echo "🔨 Building Debian package..."
+dpkg-buildpackage -b -uc -us
+
+# Check if build was successful
+if [ $? -eq 0 ]; then
+    echo "✅ Package built successfully!"
+    
+    # List generated files
+    echo "📦 Generated files:"
+    ls -la ../*.deb ../*.changes ../*.buildinfo ../*.dsc 2>/dev/null || echo "No package files found in parent directory"
+    
+    # Validate package with lintian if available
+    if command -v lintian >/dev/null 2>&1; then
+        echo "🔍 Running lintian validation..."
+        lintian ../*.changes || echo "⚠️  Lintian found some issues (see above)"
+    fi
+    
+    echo ""
+    echo "🎉 deb-bootupd Debian package built successfully!"
+    echo "📦 Install with: sudo dpkg -i ../deb-bootupd_*.deb"
+    echo "🔧 Fix dependencies with: sudo apt-get install -f"
+    
+else
+    echo "❌ Package build failed!"
+    exit 1
+fi
--- a/debian/changelog
+++ b/debian/changelog
@ -5,4 +5,4 @@ deb-bootupd (0.2.28-1) unstable; urgency=medium
  * Adapted for DPKG/APT package system
  * OSTree integration for immutable Debian deployments

- -- Debian Bootupd Team <debian-bootupd@lists.debian.org>  $(date -R)
+ -- Debian Bootupd Team <debian-bootupd@lists.debian.org>  Sat, 10 Aug 2025 11:15:00 -0700
--- a/debian/control
+++ b/debian/control
@ -11,6 +11,7 @@ Vcs-Browser: https://git.raines.xyz/robojerk/deb-bootupd
 Package: deb-bootupd
 Architecture: any
 Depends: ${shlibs:Depends}, ${misc:Depends}, efibootmgr, grub-common
+Recommends: ostree
 Description: Debian-compatible bootloader updater for immutable systems
 deb-bootupd is a sophisticated, production-ready Rust-based CLI tool that
 provides cross-distribution, OS update system agnostic bootloader management
--- a/debian/copyright
+++ b/debian/copyright
@ -0,0 +1,67 @@
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: deb-bootupd
+Upstream-Contact: Debian Bootupd Team <debian-bootupd@lists.debian.org>
+Source: https://git.raines.xyz/robojerk/deb-bootupd
+
+Files: *
+Copyright: 2025 Debian Bootupd Team
+License: MIT
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+ .
+ The above copyright notice and this permission notice shall be included in all
+ copies or substantial portions of the Software.
+ .
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ SOFTWARE.
+
+Files: debian/*
+Copyright: 2025 Debian Bootupd Team
+License: MIT
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+ .
+ The above copyright notice and this permission notice shall be included in all
+ copies or substantial portions of the Software.
+ .
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ SOFTWARE.
+
+Files: systemd/*
+Copyright: 2025 Debian Bootupd Team
+License: MIT
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+ .
+ The above copyright notice and this permission notice shall be included in all
+ copies or substantial portions of the Software.
+ .
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ SOFTWARE.
--- a/debian/debhelper-build-stamp
+++ b/debian/debhelper-build-stamp
@ -0,0 +1 @@
+deb-bootupd
--- a/debian/dirs
+++ b/debian/dirs
@ -0,0 +1,5 @@
+usr/libexec
+usr/bin
+usr/lib/systemd/system
+usr/share/doc/deb-bootupd
+usr/share/man/man1
--- a/debian/install
+++ b/debian/install
@ -0,0 +1,17 @@
+# Binary files
+target/release/bootupd usr/libexec/
+
+# Systemd service
+systemd/bootloader-update.service usr/lib/systemd/system/
+
+# Documentation
+README.md usr/share/doc/deb-bootupd/
+deb-bootupd.md usr/share/doc/deb-bootupd/
+VERSION.md usr/share/doc/deb-bootupd/
+
+# Manual pages
+debian/man/bootupctl.1 usr/share/man/man1/
+
+# Man pages (if available)
+# debian/bootupd.1 usr/share/man/man1/
+# debian/bootupctl.1 usr/share/man/man1/
--- a/debian/man/bootupctl.1
+++ b/debian/man/bootupctl.1
@ -0,0 +1,41 @@
+.TH BOOTUPCTL 1 "August 2025" "deb-bootupd" "User Commands"
+.SH NAME
+bootupctl \- bootloader update daemon control tool
+.SH SYNOPSIS
+.B bootupctl
+[\fIOPTIONS\fR] \fICOMMAND\fR [\fIARGS\fR]
+.SH DESCRIPTION
+.B bootupctl
+is a control tool for the bootupd bootloader update daemon. It provides
+commands to check system status, update bootloaders, and manage the
+bootloader update service.
+.SH COMMANDS
+.TP
+.B status
+Display the current status of bootloaders and any pending updates.
+.TP
+.B update
+Update bootloaders to the latest available versions.
+.TP
+.B help
+Show help information for available commands.
+.SH OPTIONS
+.TP
+.B \-\-help
+Show help information.
+.TP
+.B \-\-version
+Show version information.
+.SH EXAMPLES
+.TP
+Check system status:
+.B bootupctl status
+.TP
+Update bootloaders:
+.B bootupctl update
+.SH SEE ALSO
+.BR bootupd (8)
+.SH AUTHOR
+Written by the Debian Bootupd Team <debian-bootupd@lists.debian.org>
+.SH COPYRIGHT
+Copyright \(co 2025 Debian Bootupd Team. License GPLv2+: GNU GPL version 2 or later.
--- a/debian/postinst
+++ b/debian/postinst
@ -0,0 +1,34 @@
+#!/bin/sh
+set -e
+
+# Post-installation script for deb-bootupd
+# This script runs after the package is installed
+
+# Reload systemd to pick up new service files
+if command -v systemctl >/dev/null 2>&1; then
+    deb-systemd-invoke daemon-reload >/dev/null 2>&1 || true
+fi
+
+# Note: bootloader-update.service is NOT a daemon - it's a oneshot service
+# that runs bootupctl update when triggered, then exits
+# The service is enabled by default but only runs when explicitly triggered
+
+# Create initial bootupd state directory if it doesn't exist
+if [ ! -d /boot ]; then
+    mkdir -p /boot
+fi
+
+# Set proper permissions for the binary
+if [ -f /usr/libexec/bootupd ]; then
+    chmod 755 /usr/libexec/bootupd
+fi
+
+# Verify symlink was created correctly
+if [ ! -L /usr/bin/bootupctl ]; then
+    ln -sf ../libexec/bootupd /usr/bin/bootupctl
+fi
+
+echo "deb-bootupd installed successfully!"
+echo "Use 'bootupctl status' to check system status"
+echo "Use 'bootupctl update' to update bootloaders"
+echo "Note: bootupd is a CLI tool, not a daemon - it runs when called and exits"
--- a/debian/postrm
+++ b/debian/postrm
@ -0,0 +1,19 @@
+#!/bin/sh
+set -e
+
+# Post-removal script for deb-bootupd
+# This script runs after the package is removed
+
+# Reload systemd to clean up service references
+if command -v systemctl >/dev/null 2>&1; then
+    deb-systemd-invoke daemon-reload >/dev/null 2>&1 || true
+fi
+
+# Remove the symlink if it still exists
+if [ -L /usr/bin/bootupctl ]; then
+    rm -f /usr/bin/bootupctl
+fi
+
+# Note: We don't remove /boot/bootupd-state.json as it contains
+# important bootloader state that should persist across package removals
+# Users can manually remove it if they want to reset everything
--- a/debian/prerm
+++ b/debian/prerm
@ -0,0 +1,11 @@
+#!/bin/sh
+set -e
+
+# Pre-removal script for deb-bootupd
+# This script runs before the package is removed
+
+# Stop the bootloader-update service if it's running
+# Note: This is a oneshot service, so it may not be running
+if command -v systemctl >/dev/null 2>&1; then
+    deb-systemd-invoke stop bootloader-update.service >/dev/null 2>&1 || true
+fi
--- a/debian/rules
+++ b/debian/rules
@ -3,13 +3,24 @@
 %:
 	dh $@

+# Enable systemd integration
+override_dh_auto_configure:
+	dh_auto_configure
+
 override_dh_auto_build:
-	dh_cargo build --release
+	cargo build --release

 override_dh_auto_install:
-	dh_cargo install --target-dir=target/release
-	# Install systemd service files
-	install -D -m 644 systemd/bootupd.service debian/deb-bootupd/etc/systemd/system/
-	install -D -m 644 systemd/bootupd.socket debian/deb-bootupd/etc/systemd/system/
+	mkdir -p debian/deb-bootupd/usr/libexec
+	install -D -m 755 target/release/bootupd debian/deb-bootupd/usr/libexec/
 	# Create symlink for multicall binary (following RPM pattern)
-	ln -sf /usr/libexec/bootupd debian/deb-bootupd/usr/bin/bootupctl
+	ln -sf ../libexec/bootupd debian/deb-bootupd/usr/bin/bootupctl
+	# Install documentation
+	install -D -m 644 README.md debian/deb-bootupd/usr/share/doc/deb-bootupd/
+	install -D -m 644 deb-bootupd.md debian/deb-bootupd/usr/share/doc/deb-bootupd/
+	install -D -m 644 VERSION.md debian/deb-bootupd/usr/share/doc/deb-bootupd/
+
+# Clean up build artifacts
+override_dh_auto_clean:
+	dh_auto_clean
+	rm -rf target/
--- a/debian/source/format
+++ b/debian/source/format
@ -0,0 +1 @@
+3.0 (quilt)
--- a/debian/source/options
+++ b/debian/source/options
@ -0,0 +1,2 @@
+extend-diff-ignore = "^target/.*$"
+tar-ignore = target/
--- a/test-deb.sh
+++ b/test-deb.sh
@ -0,0 +1,81 @@
+#!/bin/bash
+set -e
+
+# Test script for deb-bootupd Debian package
+# This script validates and tests the built .deb package
+
+echo "🧪 Testing deb-bootupd Debian package..."
+
+# Check if package files exist
+PACKAGE_FILE=$(find .. -name "deb-bootupd_*.deb" | head -1)
+if [ -z "$PACKAGE_FILE" ]; then
+    echo "❌ Error: No deb-bootupd package found. Build the package first with ./build-deb.sh"
+    exit 1
+fi
+
+echo "📦 Found package: $PACKAGE_FILE"
+
+# Validate package structure
+echo "🔍 Validating package structure..."
+dpkg-deb -I "$PACKAGE_FILE" | grep -E "(Package|Version|Architecture|Depends|Description)" || true
+
+echo "📁 Package contents:"
+dpkg-deb -c "$PACKAGE_FILE" | head -20
+
+# Check package dependencies
+echo "🔗 Package dependencies:"
+dpkg-deb -I "$PACKAGE_FILE" | grep "Depends:" || echo "No dependencies listed"
+
+# Test package installation (dry run)
+echo "🧪 Testing package installation (dry run)..."
+dpkg --dry-run -i "$PACKAGE_FILE" || echo "⚠️  Dry run installation check failed"
+
+# Check for common packaging issues
+echo "🔍 Checking for common packaging issues..."
+
+# Check if binary is executable
+if dpkg-deb -c "$PACKAGE_FILE" | grep -q "usr/libexec/bootupd"; then
+    echo "✅ Binary found in correct location"
+else
+    echo "❌ Binary not found in usr/libexec/"
+fi
+
+# Check if symlink is present
+if dpkg-deb -c "$PACKAGE_FILE" | grep -q "usr/bin/bootupctl"; then
+    echo "✅ Symlink found in correct location"
+else
+    echo "❌ Symlink not found in usr/bin/"
+fi
+
+# Check if systemd files are NOT present (bootupd is not a daemon)
+if dpkg-deb -c "$PACKAGE_FILE" | grep -q "etc/systemd/system/bootupd.service"; then
+    echo "❌ Systemd service file found (should not be present)"
+else
+    echo "✅ No systemd service file (correct - bootupd is not a daemon)"
+fi
+
+if dpkg-deb -c "$PACKAGE_FILE" | grep -q "etc/systemd/system/bootupd.socket"; then
+    echo "❌ Systemd socket file found (should not be present)"
+else
+    echo "✅ No systemd socket file (correct - bootupd is not a daemon)"
+fi
+
+# Check if documentation is present
+if dpkg-deb -c "$PACKAGE_FILE" | grep -q "usr/share/doc/deb-bootupd"; then
+    echo "✅ Documentation directory found"
+else
+    echo "❌ Documentation directory not found"
+fi
+
+echo ""
+echo "🎯 Package validation complete!"
+echo "📦 Package file: $PACKAGE_FILE"
+echo ""
+echo "💡 To install the package:"
+echo "   sudo dpkg -i $PACKAGE_FILE"
+echo "   sudo apt-get install -f  # Fix any dependency issues"
+echo ""
+echo "💡 To test the package:"
+echo "   bootupctl --help"
+echo "   bootupctl status"
+echo "   bootupctl validate"