feat: Add reproducible Debian package builds and distribution

.github/workflows/release.yml

@@ -32,7 +32,9 @@ jobs:
             matrix:
                 arch: [aarch64-unknown-linux-gnu,
                        x86_64-unknown-linux-gnu,
-                       aarch64-apple-darwin]
+                       aarch64-apple-darwin,
+                       x86_64-unknown-linux-gnu-deb,
+                       aarch64-unknown-linux-gnu-deb]
                 include:
                     -   arch: aarch64-unknown-linux-gnu
                         runner: ${{ github.repository == 'sigp/lighthouse' && fromJson('["self-hosted", "linux", "release", "large"]') || 'ubuntu-latest'  }}
@@ -43,6 +45,17 @@ jobs:
                     -   arch: aarch64-apple-darwin
                         runner: macos-14
                         profile: maxperf
+                    # Debian package builds
+                    -   arch: x86_64-unknown-linux-gnu-deb
+                        runner: ${{ github.repository == 'sigp/lighthouse' && fromJson('["self-hosted", "linux", "release", "large"]') || 'ubuntu-latest'  }}
+                        profile: maxperf
+                        rust_target: x86_64-unknown-linux-gnu
+                        gcc_package: gcc
+                    -   arch: aarch64-unknown-linux-gnu-deb
+                        runner: ${{ github.repository == 'sigp/lighthouse' && fromJson('["self-hosted", "linux", "release", "large"]') || 'ubuntu-latest'  }}
+                        profile: maxperf
+                        rust_target: aarch64-unknown-linux-gnu
+                        gcc_package: gcc-aarch64-linux-gnu
 
         runs-on:    ${{ matrix.runner }}
         needs: extract-version
@@ -54,7 +67,25 @@ jobs:
               run: rustup update stable
 
             # ==============================
-            #       Builds
+            # Debian build dependencies
+            # ==============================
+
+            - name: Install Debian build dependencies
+              if: endsWith(matrix.arch, '-deb')
+              run: |
+                sudo apt-get update
+                sudo apt-get install -y libclang-dev cmake ${{ matrix.gcc_package }}
+
+            - name: Install Rust target for Debian builds
+              if: endsWith(matrix.arch, '-deb')
+              run: rustup target add ${{ matrix.rust_target }}
+
+            - name: Install cargo-deb
+              if: endsWith(matrix.arch, '-deb')
+              run: cargo install cargo-deb
+
+            # ==============================
+            #       Builds - Binaries
             # ==============================
 
             - name: Build Lighthouse for aarch64-unknown-linux-gnu
@@ -70,14 +101,51 @@ jobs:
                 env CROSS_PROFILE=${{ matrix.profile }} make build-x86_64
 
             - name: Move cross-compiled binary
-              if:  contains(matrix.arch, 'unknown-linux-gnu')
+              if:  contains(matrix.arch, 'unknown-linux-gnu') && !endsWith(matrix.arch, '-deb')
               run: mv target/${{ matrix.arch }}/${{ matrix.profile }}/lighthouse ~/.cargo/bin/lighthouse
 
             - name: Build Lighthouse for aarch64-apple-darwin
               if:   matrix.arch == 'aarch64-apple-darwin'
               run:  cargo install --path lighthouse --force --locked --features portable,gnosis --profile ${{ matrix.profile }}
 
+            # ==============================
+            #       Builds - Debian Packages
+            # ==============================
+
+            - name: Build reproducible Debian package
+              if: endsWith(matrix.arch, '-deb')
+              run: |
+                make deb-cargo RUST_TARGET=${{ matrix.rust_target }} PROFILE=${{ matrix.profile }}
+
+            - name: Find and prepare Debian package
+              if: endsWith(matrix.arch, '-deb')
+              run: |
+                VERSION=${{ needs.extract-version.outputs.VERSION }}
+                DEB_FILE=$(find target/${{ matrix.rust_target }}/debian -name "*.deb" | head -1)
+                if [ -n "$DEB_FILE" ]; then
+                  # Create standardized filename to match existing pattern
+                  ARCH_SHORT=$(echo "${{ matrix.rust_target }}" | cut -d'-' -f1)
+                  NEW_NAME="lighthouse-${{ needs.extract-version.outputs.VERSION }}-${ARCH_SHORT}.deb"
+                  cp "$DEB_FILE" "$NEW_NAME"
+                  echo "DEB_PACKAGE=$NEW_NAME" >> $GITHUB_ENV
+
+                  # Generate checksums  
+                  sha256sum "$NEW_NAME" > "$NEW_NAME.sha256"
+                  sha512sum "$NEW_NAME" > "$NEW_NAME.sha512"
+
+                  echo "Debian package built: $NEW_NAME"
+                  echo "Size: $(du -h "$NEW_NAME" | cut -f1)"
+                else
+                  echo "No .deb package found"
+                  exit 1
+                fi
+
+            # ==================================
+            #       Binary Artifacts (existing)
+            # ==================================
+
             - name: Configure GPG and create artifacts
+              if: startsWith(matrix.arch, 'x86_64-windows') != true && !endsWith(matrix.arch, '-deb')
               env:
                   GPG_SIGNING_KEY: ${{ secrets.GPG_SIGNING_KEY }}
                   GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
@@ -96,25 +164,70 @@ jobs:
                   done
                   mv *tar.gz* ..
 
+            # ==============================
+            #       Debian Package Artifacts
+            # ==============================
+
+            - name: Sign Debian package
+              if: endsWith(matrix.arch, '-deb')
+              env:
+                  GPG_SIGNING_KEY: ${{ secrets.GPG_SIGNING_KEY }}
+                  GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
+              run: |
+                  export GPG_TTY=$(tty)
+                  echo "$GPG_SIGNING_KEY" | gpg --batch --import
+                  echo "$GPG_PASSPHRASE" | gpg --passphrase-fd 0 --pinentry-mode loopback --batch -ab "$DEB_PACKAGE"
+
             # =======================================================================
-            # Upload artifacts
-            # This is required to share artifacts between different jobs
+            # Upload artifacts - Binaries (existing)
             # =======================================================================
 
             - name: Upload artifact
+              if: ${{ !endsWith(matrix.arch, '-deb') }}
               uses: actions/upload-artifact@v4
               with:
                   name: lighthouse-${{ needs.extract-version.outputs.VERSION }}-${{ matrix.arch }}.tar.gz
                   path: lighthouse-${{ needs.extract-version.outputs.VERSION }}-${{ matrix.arch }}.tar.gz
                   compression-level: 0
 
             - name: Upload signature
+              if: ${{ !endsWith(matrix.arch, '-deb') }}
               uses: actions/upload-artifact@v4
               with:
                   name: lighthouse-${{ needs.extract-version.outputs.VERSION }}-${{ matrix.arch }}.tar.gz.asc
                   path: lighthouse-${{ needs.extract-version.outputs.VERSION }}-${{ matrix.arch }}.tar.gz.asc
                   compression-level: 0
 
+            # =======================================================================
+            # Upload artifacts - Debian packages
+            # =======================================================================
+
+            - name: Upload Debian package
+              if: endsWith(matrix.arch, '-deb')
+              uses: actions/upload-artifact@v4
+              with:
+                  name: ${{ env.DEB_PACKAGE }}
+                  path: ${{ env.DEB_PACKAGE }}
+                  compression-level: 0
+
+            - name: Upload Debian package signature
+              if: endsWith(matrix.arch, '-deb')
+              uses: actions/upload-artifact@v4
+              with:
+                  name: ${{ env.DEB_PACKAGE }}.asc
+                  path: ${{ env.DEB_PACKAGE }}.asc
+                  compression-level: 0
+
+            - name: Upload Debian package checksums
+              if: endsWith(matrix.arch, '-deb')
+              uses: actions/upload-artifact@v4
+              with:
+                  name: ${{ env.DEB_PACKAGE }}-checksums
+                  path: |
+                      ${{ env.DEB_PACKAGE }}.sha256
+                      ${{ env.DEB_PACKAGE }}.sha512
+                  compression-level: 0
+
     draft-release:
         name:   Draft Release
         needs:  [build, extract-version]
@@ -203,11 +316,33 @@ jobs:
                   | <picture> <source media="(prefers-color-scheme: dark)" srcset="https://cdn.simpleicons.org/apple/white" > <source media="(prefers-color-scheme: light)" srcset="https://cdn.simpleicons.org/apple" ><img src="https://cdn.simpleicons.org/apple" width="32" alt="Apple logo">  </picture> | aarch64 | [lighthouse-${{ env.VERSION }}-aarch64-apple-darwin.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/lighthouse-${{ env.VERSION }}-aarch64-apple-darwin.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/lighthouse-${{ env.VERSION }}-aarch64-apple-darwin.tar.gz.asc) |
                   | <picture> <source media="(prefers-color-scheme: dark)" srcset="https://cdn.simpleicons.org/linux/white" > <source media="(prefers-color-scheme: light)" srcset="https://cdn.simpleicons.org/linux/black" ><img src="https://cdn.simpleicons.org/linux" width="32" alt="Linux logo"> </picture> | x86_64 | [lighthouse-${{ env.VERSION }}-x86_64-unknown-linux-gnu.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/lighthouse-${{ env.VERSION }}-x86_64-unknown-linux-gnu.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/lighthouse-${{ env.VERSION }}-x86_64-unknown-linux-gnu.tar.gz.asc) |
                   | <picture> <source media="(prefers-color-scheme: dark)" srcset="https://cdn.simpleicons.org/raspberrypi/white" > <source media="(prefers-color-scheme: light)" srcset="https://cdn.simpleicons.org/raspberrypi/black" > <img src="https://cdn.simpleicons.org/raspberrypi" width="32" alt="Raspberrypi logo"> </picture> | aarch64 | [lighthouse-${{ env.VERSION }}-aarch64-unknown-linux-gnu.tar.gz](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/lighthouse-${{ env.VERSION }}-aarch64-unknown-linux-gnu.tar.gz) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/lighthouse-${{ env.VERSION }}-aarch64-unknown-linux-gnu.tar.gz.asc) |
+                  ## Debian Packages
+
+                  For Debian/Ubuntu users, we provide pre-built `.deb` packages with systemd integration:
+
+                  | System | Architecture | Package | PGP Signature | Checksums |
+                  |:---:|:---:|:---:|:---:|:---:|
+                  | <picture> <source media="(prefers-color-scheme: dark)" srcset="https://cdn.simpleicons.org/debian/white" > <source media="(prefers-color-scheme: light)" srcset="https://cdn.simpleicons.org/debian/black" ><img src="https://cdn.simpleicons.org/debian" width="32" alt="Debian logo"> </picture> | x86_64 | [lighthouse-${{ env.VERSION }}-x86_64.deb](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/lighthouse-${{ env.VERSION }}-x86_64.deb) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/lighthouse-${{ env.VERSION }}-x86_64.deb.asc) | [SHA256](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/lighthouse-${{ env.VERSION }}-x86_64.deb.sha256) / [SHA512](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/lighthouse-${{ env.VERSION }}-x86_64.deb.sha512) |
+                  | <picture> <source media="(prefers-color-scheme: dark)" srcset="https://cdn.simpleicons.org/debian/white" > <source media="(prefers-color-scheme: light)" srcset="https://cdn.simpleicons.org/debian/black" ><img src="https://cdn.simpleicons.org/debian" width="32" alt="Debian logo"> </picture> | aarch64 | [lighthouse-${{ env.VERSION }}-aarch64.deb](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/lighthouse-${{ env.VERSION }}-aarch64.deb) | [PGP Signature](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/lighthouse-${{ env.VERSION }}-aarch64.deb.asc) | [SHA256](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/lighthouse-${{ env.VERSION }}-aarch64.deb.sha256) / [SHA512](https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/lighthouse-${{ env.VERSION }}-aarch64.deb.sha512) |
+
+                  ### Installation:
+                  \`\`\`bash
+                  # Download and install (x86_64)
+                  wget https://github.com/${{ env.REPO_NAME }}/releases/download/${{ env.VERSION }}/lighthouse-${{ env.VERSION }}-x86_64.deb
+                  sudo dpkg -i lighthouse-${{ env.VERSION }}-x86_64.deb
+                  sudo apt-get install -f  # Fix dependencies if needed
+
+                  # Enable and start service
+                  sudo systemctl enable lighthouse
+                  sudo systemctl start lighthouse
+                  \`\`\`
+
                   | | | | |
+                  |:---:|:---:|:---:|:---:|
                   | **System** | **Option** | - | **Resource** |
                   | <picture> <source media="(prefers-color-scheme: dark)" srcset="https://cdn.simpleicons.org/docker/white" > <source media="(prefers-color-scheme: light)" srcset="https://cdn.simpleicons.org/docker/black" > <img src="https://cdn.simpleicons.org/docker/black" width="32" alt="Docker logo"></picture>  | Docker | [${{ env.VERSION }}](https://hub.docker.com/r/${{ env.IMAGE_NAME }}/tags?page=1&ordering=last_updated&name=${{ env.VERSION }}) | [${{ env.IMAGE_NAME }}](https://hub.docker.com/r/${{ env.IMAGE_NAME }}) |
                   ENDBODY
                   )
-                  assets=(./lighthouse-*.tar.gz*/lighthouse-*.tar.gz*)
+                  assets=(./lighthouse-*.tar.gz*/lighthouse-*.tar.gz* ./lighthouse-*.deb*/lighthouse-*.deb*)
                   tag_name="${{ env.VERSION }}"
                   echo "$body" | gh release create --draft -F "-" "$tag_name" "${assets[@]}"

Makefile

@@ -332,3 +332,81 @@ clean:
 	cargo clean
 	make -C $(EF_TESTS) clean
 	make -C $(STATE_TRANSITION_VECTORS) clean
+
+.PHONY: deb-cargo
+deb-cargo: build-reproducible ## Build .deb package using cargo-deb with reproducible settings
+	@echo "Building .deb package with cargo-deb..."
+
+	cd lighthouse && \
+	SOURCE_DATE_EPOCH=$(SOURCE_DATE) \
+	CARGO_INCREMENTAL=$(CARGO_INCREMENTAL_VAL) \
+	LC_ALL=$(LOCALE_VAL) \
+	TZ=$(TZ_VAL) \
+	cargo deb --target $(RUST_TARGET) --no-build
+
+	@echo "Package built successfully!"
+	@find target/$(RUST_TARGET)/debian -name "*.deb" -exec ls -la {} \;
+
+
+.PHONY: deb-cargo-x86_64
+deb-cargo-x86_64: ## Build .deb for specific architectures
+	$(MAKE) deb-cargo RUST_TARGET=x86_64-unknown-linux-gnu
+
+.PHONY: deb-cargo-aarch64
+deb-cargo-aarch64:
+	$(MAKE) deb-cargo RUST_TARGET=aarch64-unknown-linux-gnu
+
+.PHONY: deb-cargo-all
+deb-cargo-all: deb-cargo-x86_64 deb-cargo-aarch64
+
+.PHONY: install-deb-local
+install-deb-local: ## Install .deb package locally for testing
+	@PACKAGE=$$(find target/$(RUST_TARGET)/debian -name "*.deb" | head -1); \
+	if [ -n "$$PACKAGE" ]; then \
+		echo "Installing lighthouse package: $$PACKAGE"; \
+		sudo dpkg -i "$$PACKAGE"; \
+		echo "Fixing dependencies if needed..."; \
+		sudo apt-get install -f; \
+		echo "Package installed successfully!"; \
+		echo ""; \
+		echo "The lighthouse service is now available but not started."; \
+		echo "Your systemd service file handles user creation declaratively."; \
+		echo ""; \
+		echo "To check service status: systemctl status lighthouse"; \
+	else \
+		echo "No .deb package found. Run 'make deb-cargo' first."; \
+	fi
+
+
+.PHONY: remove-deb-local
+remove-deb-local: ## Remove installed lighthouse package
+	@echo "Removing lighthouse package..."
+	sudo dpkg -r lighthouse || true
+	sudo systemctl daemon-reload || true
+
+.PHONY: clean-deb
+clean-deb: ## Clean up debian packaging artifacts
+	@echo "Cleaning up debian packaging artifacts..."
+	rm -f lighthouse_*.deb lighthouse-deb-*.deb *-diff.txt
+	rm -rf target/*/debian/
+
+
+.PHONY: help-deb
+help-deb: ## Show help for debian packaging
+	@echo "Clean Debian Packaging Targets:"
+	@echo "  deb-cargo              - Build .deb package with cargo-deb"
+	@echo "  deb-cargo-x86_64       - Build x86_64 .deb package"
+	@echo "  deb-cargo-aarch64      - Build aarch64 .deb package"
+	@echo "  deb-cargo-all          - Build all architectures"
+	@echo "  test-deb-reproducible  - Test reproducibility"
+	@echo "  install-deb-local      - Install .deb package locally"
+	@echo "  remove-deb-local       - Remove installed package"
+	@echo "  clean-deb              - Clean up packaging artifacts"
+	@echo ""
+	@echo "Prerequisites:"
+	@echo "  - lighthouse/lighthouse.service file"  
+	@echo "  - README.md file in current directory"
+	@echo ""
+	@echo "Quick start:"
+	@echo "  make deb-cargo         - Build .deb for current RUST_TARGET"
+	@echo "  make install-deb-local - Test the package"

lighthouse/Cargo.toml

@@ -96,3 +96,26 @@ zeroize = { workspace = true }
 [[test]]
 name = "lighthouse_tests"
 path = "tests/main.rs"
+
+[package.metadata.deb]
+maintainer = "Sigma Prime <team@sigmaprime.io>"
+extended-description = """\
+Lighthouse is a Rust implementation of the Ethereum beacon chain, \
+built by Sigma Prime. It implements the official Ethereum 2.0 specification."""
+
+depends = "$auto, systemd"
+section = "net"
+priority = "optional"
+maintainer-scripts = "debian/"  # This tells cargo-deb where to find scripts
+
+# System integration
+systemd-units = { enable = false, start = false }
+
+# Assets to include in the package
+assets = [
+    ["target/release/lighthouse", "usr/bin/", "755"],
+    ["debian/lighthouse.service", "lib/systemd/system/", "644"],
+    ["../README.md", "usr/share/doc/lighthouse/", "644"],
+]
+
+default-features = false

lighthouse/debian/lighthouse.service

@@ -0,0 +1,16 @@
+[Unit]
+Description=Lighthouse Ethereum Beacon Node
+After=network.target
+Wants=network.target
+
+[Service]
+Type=exec
+DynamicUser=yes
+StateDirectory=lighthouse
+ExecStart=/usr/bin/lighthouse bn \
+          --execution-endpoint http://localhost:8551 \
+          --execution-jwt-secret-key 0000000000000000000000000000000000000000000000000000000000000000
+          --datadir %S/lighthouse
+
+[Install]
+WantedBy=default.target

lighthouse/debian/postinst

@@ -0,0 +1,25 @@
+#!/bin/sh
+set -e
+
+# Create lighthouse user if it doesn't exist
+if ! getent passwd lighthouse >/dev/null 2>&1; then
+    adduser --system --group --home /var/lib/lighthouse \
+            --shell /bin/false --gecos "Lighthouse Beacon Node" lighthouse
+fi
+
+# Create data directory
+mkdir -p /var/lib/lighthouse
+chown lighthouse:lighthouse /var/lib/lighthouse
+chmod 750 /var/lib/lighthouse
+
+# Create log directory  
+mkdir -p /var/log/lighthouse
+chown lighthouse:lighthouse /var/log/lighthouse
+chmod 750 /var/log/lighthouse
+
+# Reload systemd
+systemctl daemon-reload || true
+
+#DEBHELPER#
+
+exit 0

lighthouse/debian/postrm

@@ -0,0 +1,17 @@
+#!/bin/sh
+set -e
+
+if [ "$1" = "purge" ]; then
+    # Remove user (optional - some prefer to keep it)
+    if getent passwd lighthouse >/dev/null 2>&1; then
+        deluser lighthouse || true
+    fi
+
+    # Remove data directory (be careful!)
+    # rm -rf /var/lib/lighthouse || true
+    # rm -rf /var/log/lighthouse || true
+fi
+
+#DEBHELPER#
+
+exit 0

lighthouse/debian/prerm

@@ -0,0 +1,12 @@
+#!/bin/sh
+set -e
+
+if [ "$1" = "remove" ]; then
+    # Stop service if running
+    systemctl stop lighthouse || true
+    systemctl disable lighthouse || true
+fi
+
+#DEBHELPER#
+
+exit 0