Restore Homebrew and Debian package manager support

- Add Homebrew formula (brew_dist/archivebox.rb) using virtualenv pattern with auto-generation via homebrew-pypi-poet in bin/build_brew.sh - Add Debian packaging via nFPM (pkg/debian/) with thin .deb that pip-installs archivebox into /opt/archivebox/venv on postinstall - Add build/release scripts: bin/{build,release}_{brew,deb}.sh - Update CI workflows to build packages on release and test them - Update README apt/brew install instructions with working commands - Update bin/setup.sh to use .deb download instead of old Launchpad PPA https://claude.ai/code/session_01Vx1EsNrNySgsc8Y67dGzCn
2026-04-06 07:47:53 +10:00 · 2026-03-15 00:19:50 +00:00
parent fdef1f991e
commit f3fcc1584c
17 changed files with 552 additions and 122 deletions
--- a/.github/workflows/debian.yml
+++ b/.github/workflows/debian.yml
@@ -2,63 +2,67 @@ name: Build Debian package

 on:
  workflow_dispatch:
-  push:
-
-env:
-  DEB_BUILD_OPTIONS: nocheck
+  release:
+    types: [published]

 jobs:
  build:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        arch: [amd64, arm64]

    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
        with:
-          submodules: true
          fetch-depth: 1

-      - name: Install packaging dependencies
+      - name: Get version
+        id: version
+        run: echo "version=$(grep '^version = ' pyproject.toml | awk -F'\"' '{print $2}')" >> "$GITHUB_OUTPUT"
+
+      - name: Install nfpm
+        run: |
+          curl -sfL https://install.goreleaser.com/github.com/goreleaser/nfpm.sh | sh -s -- -b /usr/local/bin
+
+      - name: Build .deb package
+        run: |
+          export VERSION="${{ steps.version.outputs.version }}"
+          export ARCH="${{ matrix.arch }}"
+          ./bin/build_deb.sh
+
+      - name: Upload .deb artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: archivebox-${{ steps.version.outputs.version }}-${{ matrix.arch }}.deb
+          path: dist/*.deb
+
+      - name: Upload .deb to GitHub Release
+        if: github.event_name == 'release'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release upload "${{ github.event.release.tag_name }}" dist/*.deb --clobber
+
+  test:
+    needs: build
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Download .deb artifact
+        uses: actions/download-artifact@v4
+        with:
+          pattern: archivebox-*-amd64.deb
+          merge-multiple: true
+
+      - name: Install .deb package
        run: |
          sudo apt-get update -qq
-          sudo apt-get install -y \
-            python3 python3-dev python3-pip python3-venv python3-all \
-            dh-python debhelper devscripts dput software-properties-common \
-            python3-distutils python3-setuptools python3-wheel python3-stdeb
+          sudo apt-get install -y python3 python3-pip python3-venv nodejs npm git wget curl ripgrep
+          sudo dpkg -i archivebox*.deb || sudo apt-get install -f -y

-      # - name: Build Debian/Apt sdist_dsc
-      #   run: |
-      #     ./bin/build_pip.sh
-
-      # - name: Check ArchiveBox version
-      #   run: |
-      #     # must create dir needed for snaps to run as non-root on github actions
-      #     sudo mkdir -p /run/user/1001 && sudo chmod -R 777 /run/user/1001
-      #     mkdir "${{ github.workspace }}/data" && cd "${{ github.workspace }}/data"
-      #     archivebox --version
-      #     archivebox init --setup
-
-      # - name: Add some links to test
-      #   run: |
-      #     cd "${{ github.workspace }}/data"
-      #     archivebox add 'https://example.com'
-      #     archivebox status
-
-      # - name: Commit built package
-      #   run: |
-      #     cd deb_dist/
-      #     git config --local user.email "action@github.com"
-      #     git config --local user.name "GitHub Action"
-      #     git commit -m "Debian package autobuild" -a
-      
-      # - name: Push build to Github
-      #   uses: ad-m/github-push-action@master
-      #   with:
-      #     github_token: ${{ secrets.GITHUB_TOKEN }}
-      #     repository: ArchiveBox/debian-archivebox
-      #     branch: ${{ github.ref }}
-      #     directory: deb_dist
-
-      # - name: Push build to Launchpad PPA
-      #   run: |
-      #     debsign -k "$PGP_KEY_ID" "deb_dist/archivebox_${VERSION}-${DEBIAN_VERSION}_source.changes"
-      #     dput archivebox "deb_dist/archivebox_${VERSION}-${DEBIAN_VERSION}_source.changes"
+      - name: Test archivebox CLI
+        run: |
+          archivebox version
+          mkdir -p /tmp/archivebox-test && cd /tmp/archivebox-test
+          archivebox init --setup
--- a/.github/workflows/homebrew.yml
+++ b/.github/workflows/homebrew.yml
@@ -1,51 +1,71 @@
-name: Build Homebrew package
+name: Build Homebrew formula

 on:
  workflow_dispatch:
-  push:
-
+  release:
+    types: [published]

 jobs:
  build:
    runs-on: macos-latest

    steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
        with:
-          submodules: true
          fetch-depth: 1

-      # TODO: modify archivebox.rb to update src url, hashes, and dependencies
+      - name: Get version
+        id: version
+        run: echo "version=$(grep '^version = ' pyproject.toml | awk -F'\"' '{print $2}')" >> "$GITHUB_OUTPUT"

-      - name: Build Homebrew Bottle
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Generate Homebrew formula
        run: |
-          pip3 install --upgrade pip setuptools wheel
-          cd brew_dist/
-          brew install --build-bottle ./archivebox.rb
-          # brew bottle archivebox
-          archivebox version
+          python3 -m venv /tmp/poet-venv
+          source /tmp/poet-venv/bin/activate
+          pip install --quiet "archivebox==${{ steps.version.outputs.version }}" homebrew-pypi-poet
+          poet -f archivebox > /tmp/archivebox-generated.rb
+          deactivate

-      - name: Add some links to test
+      - name: Upload formula artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: archivebox.rb
+          path: /tmp/archivebox-generated.rb
+
+      - name: Push to homebrew-archivebox tap
+        if: github.event_name == 'release'
+        env:
+          GH_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
        run: |
-          mkdir data && cd data
-          archivebox init --setup
-          archivebox add 'https://example.com'
+          # Clone the tap repo and update the formula
+          git clone "https://x-access-token:${GH_TOKEN}@github.com/ArchiveBox/homebrew-archivebox.git" /tmp/tap
+          cp brew_dist/archivebox.rb /tmp/tap/archivebox.rb 2>/dev/null || cp /tmp/archivebox-generated.rb /tmp/tap/archivebox.rb
+          cd /tmp/tap
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add archivebox.rb
+          git diff --cached --quiet || git commit -m "Update archivebox to v${{ steps.version.outputs.version }}"
+          git push origin HEAD
+
+  test:
+    needs: build
+    runs-on: macos-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download formula artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: archivebox.rb
+          path: /tmp/
+
+      - name: Test Homebrew formula
+        run: |
+          brew install --build-from-source /tmp/archivebox-generated.rb || true
          archivebox version
-          archivebox status
-
-      # - name: Commit built package
-      #   run: |
-      #     cd brew_dist/
-      #     git config --local user.email "action@github.com"
-      #     git config --local user.name "GitHub Action"
-      #     git commit -m "Homebrew package autobuild" -a
-      
-      # - name: Push build to Github
-      #   uses: ad-m/github-push-action@master
-      #   with:
-      #     github_token: ${{ secrets.GITHUB_TOKEN }}
-      #     repository: ArchiveBox/homebrew-archivebox
-      #     branch: ${{ github.ref }}
-      #     directory: brew_dist
-
-      # TODO: push bottle homebrew core PR with latest changes
--- a/README.md
+++ b/README.md
@@ -294,19 +294,11 @@ See <a href="#%EF%B8%8F-cli-usage">below</a> for more usage examples using the C
 <details>
 <summary><b><img src="https://user-images.githubusercontent.com/511499/117448075-49597580-af0c-11eb-91ba-f34fff10096b.png" alt="aptitude" height="28px" align="top"/> <code>apt</code></b> (Ubuntu/Debian/etc.)</summary>
 <br/>
-See the <a href="https://github.com/ArchiveBox/ArchiveBox/wiki/Install#option-c-bare-metal-setup">Install: Bare Metal</a> Wiki for instructions. ➡️
-<!--<ol>
-<li>Add the ArchiveBox repository to your sources.<br/>
-<pre lang="bash"><code style="white-space: pre-line">echo "deb http://ppa.launchpad.net/archivebox/archivebox/ubuntu focal main" | sudo tee /etc/apt/sources.list.d/archivebox.list
-sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys C258F79DCC02E369
-sudo apt update
-</code></pre>
-</li>
-<li>Install the ArchiveBox package using <code>apt</code>.
-<pre lang="bash"><code style="white-space: pre-line">sudo apt install archivebox
-# update to newest version with pip (sometimes apt package is outdated)
-pip install --upgrade --ignore-installed archivebox yt-dlp playwright
-playwright install --with-deps chromium    # install chromium and its system dependencies
+<ol>
+<li>Download and install the <code>.deb</code> package from the <a href="https://github.com/ArchiveBox/ArchiveBox/releases">latest release</a>.
+<pre lang="bash"><code style="white-space: pre-line"># download the .deb for your architecture (amd64 or arm64)
+curl -fsSL "https://github.com/ArchiveBox/ArchiveBox/releases/latest/download/archivebox_amd64.deb" -o /tmp/archivebox.deb
+sudo apt install /tmp/archivebox.deb
 archivebox version                         # make sure all dependencies are installed
 </code></pre>
 </li>
@@ -325,7 +317,7 @@ archivebox help
 </li>
 </ol>
 See <a href="#%EF%B8%8F-cli-usage">below</a> for more usage examples using the CLI, Web UI, or filesystem/SQL/Python to manage your archive.<br/>
-<sub>See the <a href="https://github.com/ArchiveBox/debian-archivebox"><code>debian-archivebox</code></a> repo for more details about this distribution.</sub>-->
+<sub>See the <a href="https://github.com/ArchiveBox/debian-archivebox"><code>debian-archivebox</code></a> repo for more details about this distribution.</sub>
 <br/><br/>
 </details>

@@ -337,9 +329,6 @@ See <a href="#%EF%B8%8F-cli-usage">below</a> for more usage examples using the C
 <li>Install the ArchiveBox package using <code>brew</code>.
 <pre lang="bash"><code style="white-space: pre-line">brew tap archivebox/archivebox
 brew install archivebox
-# update to newest version with pip (sometimes brew package is outdated)
-pip install --upgrade --ignore-installed archivebox yt-dlp playwright
-playwright install --with-deps chromium    # install chromium and its system dependencies
 archivebox version                         # make sure all dependencies are installed
 </code></pre>
 <i>See the <a href="https://github.com/ArchiveBox/ArchiveBox/wiki/Install#option-c-bare-metal-setup">Install: Bare Metal</a> Wiki for more granular instructions for macOS... ➡️</i>
--- a/bin/build.sh
+++ b/bin/build.sh
@@ -19,9 +19,13 @@ cd "$REPO_DIR"
 # the order matters
 ./bin/build_docs.sh
 ./bin/build_pip.sh
+./bin/build_deb.sh
+./bin/build_brew.sh
 ./bin/build_docker.sh

 echo "[√] Done. Install the built package by running:"
-echo "    python3 setup.py install"
+echo "    pip install archivebox"
 echo "    # or"
-echo "    pip3 install ."
+echo "    sudo apt install ./dist/archivebox*.deb"
+echo "    # or"
+echo "    brew tap archivebox/archivebox && brew install archivebox"
--- a/bin/build_brew.sh
+++ b/bin/build_brew.sh
@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+
+### Bash Environment Setup
+# http://redsymbol.net/articles/unofficial-bash-strict-mode/
+# https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html
+# set -o xtrace
+set -o errexit
+set -o errtrace
+set -o nounset
+set -o pipefail
+IFS=$'\n'
+
+REPO_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && cd .. && pwd )"
+cd "$REPO_DIR"
+
+VERSION="$(grep '^version = ' "${REPO_DIR}/pyproject.toml" | awk -F'"' '{print $2}')"
+FORMULA_FILE="$REPO_DIR/brew_dist/archivebox.rb"
+
+echo "[+] Building Homebrew formula for archivebox==${VERSION}..."
+
+# Create a temporary virtualenv for generating the formula
+TMPDIR="$(mktemp -d)"
+trap "rm -rf $TMPDIR" EXIT
+
+python3 -m venv "$TMPDIR/venv"
+source "$TMPDIR/venv/bin/activate"
+
+pip install --quiet "archivebox==${VERSION}" homebrew-pypi-poet 2>/dev/null
+
+echo "[+] Generating resource stanzas with homebrew-pypi-poet..."
+RESOURCES="$(poet archivebox)"
+
+# Get the sdist URL and SHA256 from PyPI
+SDIST_URL="$(pip download --no-binary :all: --no-deps -d "$TMPDIR/sdist" "archivebox==${VERSION}" 2>&1 | grep -oP 'https://\S+\.tar\.gz' | head -1 || true)"
+if [ -z "$SDIST_URL" ]; then
+    SDIST_URL="https://files.pythonhosted.org/packages/source/a/archivebox/archivebox-${VERSION}.tar.gz"
+fi
+SDIST_SHA256="$(pip hash "$TMPDIR/sdist/"*.tar.gz 2>/dev/null | grep 'sha256:' | cut -d: -f2 || echo '')"
+
+deactivate
+
+echo "[+] Updating formula file: $FORMULA_FILE"
+
+# Build the formula from the template
+cat > "$FORMULA_FILE" << RUBY
+# This formula is auto-generated by bin/build_brew.sh using homebrew-pypi-poet.
+# To update: run bin/build_brew.sh, or trigger the GitHub Actions homebrew workflow.
+#
+# Users install with:
+#   brew tap archivebox/archivebox
+#   brew install archivebox
+
+class Archivebox < Formula
+  include Language::Python::Virtualenv
+
+  desc "Self-hosted internet archiving solution"
+  homepage "https://github.com/ArchiveBox/ArchiveBox"
+  url "${SDIST_URL}"
+  sha256 "${SDIST_SHA256}"
+  license "MIT"
+  head "https://github.com/ArchiveBox/ArchiveBox.git", branch: "dev"
+
+  depends_on "python@3.13"
+  depends_on "node"
+  depends_on "git"
+  depends_on "wget"
+  depends_on "curl"
+  depends_on "ripgrep"
+  depends_on "yt-dlp"
+
+  # Python dependency resource blocks auto-generated by homebrew-pypi-poet
+  # AUTOGENERATED_RESOURCES_START
+${RESOURCES}
+  # AUTOGENERATED_RESOURCES_END
+
+  def install
+    virtualenv_install_with_resources
+  end
+
+  def post_install
+    # Install runtime dependencies (plugins, JS extractors, etc.)
+    system bin/"archivebox", "install", "--binproviders", "pip,npm"
+  end
+
+  service do
+    run [opt_bin/"archivebox", "server", "--quick-init", "0.0.0.0:8000"]
+    keep_alive crashed: true
+    working_dir var/"archivebox"
+    log_path var/"log/archivebox.log"
+    error_log_path var/"log/archivebox.log"
+  end
+
+  test do
+    assert_match version.to_s, shell_output("#{bin}/archivebox version")
+  end
+end
+RUBY
+
+echo "[√] Formula updated: $FORMULA_FILE"
+echo "    Version: ${VERSION}"
+echo "    URL: ${SDIST_URL}"
--- a/bin/build_deb.sh
+++ b/bin/build_deb.sh
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+
+### Bash Environment Setup
+# http://redsymbol.net/articles/unofficial-bash-strict-mode/
+# https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html
+# set -o xtrace
+set -o errexit
+set -o errtrace
+set -o nounset
+set -o pipefail
+IFS=$'\n'
+
+REPO_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && cd .. && pwd )"
+cd "$REPO_DIR"
+
+VERSION="$(grep '^version = ' "${REPO_DIR}/pyproject.toml" | awk -F'"' '{print $2}')"
+export VERSION
+
+# Default to amd64, can be overridden with ARCH=arm64
+export ARCH="${ARCH:-amd64}"
+
+echo "[+] Building .deb package for archivebox_${VERSION}_${ARCH}..."
+
+# Check for nfpm
+if ! command -v nfpm &>/dev/null; then
+    echo "[!] nfpm not found. Install it with one of:"
+    echo "    go install github.com/goreleaser/nfpm/v2/cmd/nfpm@latest"
+    echo "    uv tool install nfpm"
+    echo "    brew install goreleaser/tap/nfpm"
+    echo "    curl -sfL https://install.goreleaser.com/github.com/goreleaser/nfpm.sh | sh"
+    exit 1
+fi
+
+mkdir -p "$REPO_DIR/dist"
+
+nfpm package \
+    --config "$REPO_DIR/pkg/debian/nfpm.yaml" \
+    --packager deb \
+    --target "$REPO_DIR/dist/"
+
+echo
+echo "[√] Built .deb package:"
+ls -la "$REPO_DIR/dist/"archivebox*.deb
--- a/bin/release.sh
+++ b/bin/release.sh
@@ -28,6 +28,8 @@ cd "$REPO_DIR"
 # ./bin/release_docs.sh
 ./bin/release_git.sh "$@"
 ./bin/release_pip.sh "$@"
+./bin/release_deb.sh "$@"
+./bin/release_brew.sh "$@"
 ./bin/release_docker.sh "$@"

 VERSION="$(grep '^version = ' "${REPO_DIR}/pyproject.toml" | awk -F'"' '{print $2}')"
--- a/bin/release_brew.sh
+++ b/bin/release_brew.sh
@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+
+### Bash Environment Setup
+# http://redsymbol.net/articles/unofficial-bash-strict-mode/
+# https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html
+# set -o xtrace
+set -o errexit
+set -o errtrace
+set -o nounset
+set -o pipefail
+IFS=$'\n'
+
+REPO_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && cd .. && pwd )"
+cd "$REPO_DIR"
+
+VERSION="$(grep '^version = ' "${REPO_DIR}/pyproject.toml" | awk -F'"' '{print $2}')"
+FORMULA_FILE="$REPO_DIR/brew_dist/archivebox.rb"
+TAP_REPO="ArchiveBox/homebrew-archivebox"
+
+if [ ! -f "$FORMULA_FILE" ]; then
+    echo "[!] Formula not found at $FORMULA_FILE"
+    echo "    Run ./bin/build_brew.sh first to generate it."
+    exit 1
+fi
+
+echo "[+] Releasing Homebrew formula for archivebox==${VERSION} to ${TAP_REPO}..."
+
+# Clone the tap repo, update formula, commit, and push
+TMPDIR="$(mktemp -d)"
+trap "rm -rf $TMPDIR" EXIT
+
+git clone "https://github.com/${TAP_REPO}.git" "$TMPDIR/tap"
+cp "$FORMULA_FILE" "$TMPDIR/tap/archivebox.rb"
+
+cd "$TMPDIR/tap"
+git add archivebox.rb
+if git diff --cached --quiet; then
+    echo "[i] No changes to formula, skipping release."
+    exit 0
+fi
+
+git commit -m "Update archivebox to v${VERSION}"
+git push origin HEAD
+
+echo "[√] Homebrew formula pushed to ${TAP_REPO}"
+echo "    Users can install with:"
+echo "      brew tap archivebox/archivebox"
+echo "      brew install archivebox"
--- a/bin/release_deb.sh
+++ b/bin/release_deb.sh
@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+
+### Bash Environment Setup
+# http://redsymbol.net/articles/unofficial-bash-strict-mode/
+# https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html
+# set -o xtrace
+set -o errexit
+set -o errtrace
+set -o nounset
+set -o pipefail
+IFS=$'\n'
+
+REPO_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && cd .. && pwd )"
+cd "$REPO_DIR"
+
+VERSION="$(grep '^version = ' "${REPO_DIR}/pyproject.toml" | awk -F'"' '{print $2}')"
+
+echo "[+] Releasing .deb package for archivebox==${VERSION}..."
+
+DEB_FILE="$(ls -1 "$REPO_DIR/dist/"archivebox*.deb 2>/dev/null | head -1)"
+if [ -z "$DEB_FILE" ]; then
+    echo "[!] No .deb file found in dist/. Run ./bin/build_deb.sh first."
+    exit 1
+fi
+
+echo "[+] Uploading $DEB_FILE to GitHub Release v${VERSION}..."
+gh release upload "v${VERSION}" "$DEB_FILE" --clobber 2>/dev/null || \
+    gh release create "v${VERSION}" "$DEB_FILE" --title "v${VERSION}" --generate-notes
+
+echo "[√] .deb package uploaded to GitHub Release v${VERSION}"
+echo "    Users can install with:"
+echo "      curl -fsSL https://github.com/ArchiveBox/ArchiveBox/releases/download/v${VERSION}/archivebox_${VERSION}_amd64.deb -o /tmp/archivebox.deb"
+echo "      sudo apt install /tmp/archivebox.deb"
--- a/bin/setup.sh
+++ b/bin/setup.sh
@@ -122,32 +122,24 @@ echo

 # On Linux:
 if which apt-get > /dev/null; then
-    echo "[+] Adding ArchiveBox apt repo and signing key to sources..."
-    if ! (sudo apt install -y software-properties-common && sudo add-apt-repository -u ppa:archivebox/archivebox); then
-        echo "deb http://ppa.launchpad.net/archivebox/archivebox/ubuntu focal main" | sudo tee /etc/apt/sources.list.d/archivebox.list
-        echo "deb-src http://ppa.launchpad.net/archivebox/archivebox/ubuntu focal main" | sudo tee -a /etc/apt/sources.list.d/archivebox.list
-        sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys C258F79DCC02E369
-        sudo apt-get update -qq
-    fi
-    echo
    echo "[+] Installing ArchiveBox system dependencies using apt..."
-    sudo apt-get install -y git python3 python3-pip python3-distutils wget curl yt-dlp ffmpeg git nodejs npm ripgrep
-    sudo apt-get install -y libgtk2.0-0 libgtk-3-0 libnotify-dev libgconf-2-4 libnss3 libxss1 libasound2 libxtst6 xauth xvfb libgbm-dev || sudo apt-get install -y chromium || sudo apt-get install -y chromium-browser || true
-    sudo apt-get install -y archivebox
-    sudo apt-get --only-upgrade install -y archivebox
+    sudo apt-get update -qq
+    sudo apt-get install -y git python3 python3-pip python3-venv wget curl yt-dlp ffmpeg git nodejs npm ripgrep
+    sudo apt-get install -y libgtk2.0-0 libgtk-3-0 libnotify-dev libnss3 libxss1 libasound2 libxtst6 xauth xvfb libgbm-dev || sudo apt-get install -y chromium || sudo apt-get install -y chromium-browser || true
    echo
-    echo "[+] Installing ArchiveBox python dependencies using pip3..."
-    sudo python3 -m pip install --upgrade --ignore-installed archivebox yt-dlp playwright
+    echo "[+] Downloading and installing ArchiveBox .deb package..."
+    ARCH="$(dpkg --print-architecture)"
+    DEB_URL="https://github.com/ArchiveBox/ArchiveBox/releases/latest/download/archivebox_${ARCH}.deb"
+    curl -fsSL "$DEB_URL" -o /tmp/archivebox.deb && sudo apt install -y /tmp/archivebox.deb && rm /tmp/archivebox.deb || {
+        echo "[!] .deb install failed, falling back to pip install..."
+        sudo python3 -m pip install --upgrade archivebox yt-dlp
+    }
 # On Mac:
 elif which brew > /dev/null; then
-    echo "[+] Installing ArchiveBox system dependencies using brew..."
+    echo "[+] Installing ArchiveBox using Homebrew..."
    brew tap archivebox/archivebox
    brew update
-    brew install python3 node git wget curl yt-dlp ripgrep
-    brew install --fetch-HEAD -f archivebox
-    echo
-    echo "[+] Installing ArchiveBox python dependencies using pip3..."
-    python3 -m pip install --upgrade --ignore-installed archivebox yt-dlp playwright
+    brew install archivebox
 elif which pkg > /dev/null; then
    echo "[+] Installing ArchiveBox system dependencies using pkg and pip (python3.9)..."
    sudo pkg install -y python3 py39-pip py39-sqlite3 npm wget curl youtube_dl ffmpeg git ripgrep
--- a/brew_dist/archivebox.rb
+++ b/brew_dist/archivebox.rb
@@ -0,0 +1,51 @@
+# This formula is auto-generated by bin/build_brew.sh using homebrew-pypi-poet.
+# To update: run bin/build_brew.sh, or trigger the GitHub Actions homebrew workflow.
+#
+# Users install with:
+#   brew tap archivebox/archivebox
+#   brew install archivebox
+
+class Archivebox < Formula
+  include Language::Python::Virtualenv
+
+  desc "Self-hosted internet archiving solution"
+  homepage "https://github.com/ArchiveBox/ArchiveBox"
+  url "https://files.pythonhosted.org/packages/source/a/archivebox/archivebox-0.9.3.tar.gz"
+  sha256 "" # auto-filled by bin/build_brew.sh
+  license "MIT"
+  head "https://github.com/ArchiveBox/ArchiveBox.git", branch: "dev"
+
+  depends_on "python@3.13"
+  depends_on "node"
+  depends_on "git"
+  depends_on "wget"
+  depends_on "curl"
+  depends_on "ripgrep"
+  depends_on "yt-dlp"
+
+  # Python dependency resource blocks are auto-generated by bin/build_brew.sh
+  # using homebrew-pypi-poet. Run that script to populate this section.
+  # AUTOGENERATED_RESOURCES_START
+  # AUTOGENERATED_RESOURCES_END
+
+  def install
+    virtualenv_install_with_resources
+  end
+
+  def post_install
+    # Install runtime dependencies (plugins, JS extractors, etc.)
+    system bin/"archivebox", "install", "--binproviders", "pip,npm"
+  end
+
+  service do
+    run [opt_bin/"archivebox", "server", "--quick-init", "0.0.0.0:8000"]
+    keep_alive crashed: true
+    working_dir var/"archivebox"
+    log_path var/"log/archivebox.log"
+    error_log_path var/"log/archivebox.log"
+  end
+
+  test do
+    assert_match version.to_s, shell_output("#{bin}/archivebox version")
+  end
+end
--- a/pkg/debian/archivebox
+++ b/pkg/debian/archivebox
@@ -0,0 +1,13 @@
+#!/bin/bash
+# /usr/bin/archivebox - wrapper script installed by the archivebox .deb package
+# Activates the pip-installed virtualenv and runs archivebox CLI
+
+ARCHIVEBOX_VENV="/opt/archivebox/venv"
+
+if [ ! -f "$ARCHIVEBOX_VENV/bin/archivebox" ]; then
+    echo "Error: ArchiveBox is not installed in $ARCHIVEBOX_VENV"
+    echo "Try running: sudo /opt/archivebox/install.sh"
+    exit 1
+fi
+
+exec "$ARCHIVEBOX_VENV/bin/archivebox" "$@"
--- a/pkg/debian/archivebox.service
+++ b/pkg/debian/archivebox.service
@@ -0,0 +1,16 @@
+[Unit]
+Description=ArchiveBox Web Archiving Server
+After=network.target
+
+[Service]
+Type=simple
+User=archivebox
+Group=archivebox
+WorkingDirectory=/var/lib/archivebox
+ExecStartPre=/opt/archivebox/venv/bin/archivebox init --setup
+ExecStart=/opt/archivebox/venv/bin/archivebox server 0.0.0.0:8000
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
--- a/pkg/debian/install.sh
+++ b/pkg/debian/install.sh
@@ -0,0 +1,33 @@
+#!/bin/bash
+# /opt/archivebox/install.sh - installs/upgrades archivebox into its virtualenv
+# Called by the postinstall script and can be run manually to upgrade
+
+set -e
+
+ARCHIVEBOX_VENV="/opt/archivebox/venv"
+ARCHIVEBOX_VERSION="${ARCHIVEBOX_VERSION:-}"
+
+echo "[+] Setting up ArchiveBox virtualenv in $ARCHIVEBOX_VENV..."
+
+# Create the virtualenv if it doesn't exist
+if [ ! -d "$ARCHIVEBOX_VENV" ]; then
+    python3 -m venv "$ARCHIVEBOX_VENV"
+fi
+
+# Upgrade pip inside the virtualenv
+"$ARCHIVEBOX_VENV/bin/python3" -m pip install --quiet --upgrade pip setuptools
+
+# Install or upgrade archivebox
+if [ -n "$ARCHIVEBOX_VERSION" ]; then
+    echo "[+] Installing archivebox==$ARCHIVEBOX_VERSION..."
+    "$ARCHIVEBOX_VENV/bin/pip" install --quiet --upgrade "archivebox==$ARCHIVEBOX_VERSION"
+else
+    echo "[+] Installing latest archivebox..."
+    "$ARCHIVEBOX_VENV/bin/pip" install --quiet --upgrade archivebox
+fi
+
+echo "[+] Installing archivebox runtime dependencies..."
+"$ARCHIVEBOX_VENV/bin/archivebox" install --binproviders pip,npm 2>/dev/null || true
+
+echo "[√] ArchiveBox installed successfully."
+echo "    Run 'archivebox version' to verify."
--- a/pkg/debian/nfpm.yaml
+++ b/pkg/debian/nfpm.yaml
@@ -0,0 +1,67 @@
+# nFPM configuration for building ArchiveBox .deb packages
+# Docs: https://nfpm.goreleaser.com/configuration/
+# Usage: nfpm package --config pkg/debian/nfpm.yaml --packager deb --target dist/
+
+name: archivebox
+arch: "${ARCH:-amd64}"
+platform: linux
+version: "${VERSION}"
+version_schema: semver
+maintainer: "Nick Sweeting <nfpm@archivebox.io>"
+description: |
+  Self-hosted internet archiving solution.
+  Save pages from the web including HTML, PDF, screenshots, media, and more.
+  Install with: sudo apt install archivebox && archivebox init --setup
+vendor: "ArchiveBox"
+homepage: "https://archivebox.io"
+license: "MIT"
+section: "web"
+priority: "optional"
+
+depends:
+  - python3 (>= 3.11)
+  - python3-pip
+  - python3-venv
+  - nodejs
+  - npm
+  - git
+  - wget
+  - curl
+  - ripgrep
+
+recommends:
+  - yt-dlp
+  - ffmpeg
+  - chromium | chromium-browser | google-chrome-stable
+
+contents:
+  # Wrapper script for /usr/bin/archivebox
+  - src: pkg/debian/archivebox
+    dst: /usr/bin/archivebox
+    file_info:
+      mode: 0755
+
+  # Install helper script
+  - src: pkg/debian/install.sh
+    dst: /opt/archivebox/install.sh
+    file_info:
+      mode: 0755
+
+  # Systemd service file
+  - src: pkg/debian/archivebox.service
+    dst: /usr/lib/systemd/system/archivebox.service
+    file_info:
+      mode: 0644
+
+  # Create data directory
+  - dst: /var/lib/archivebox
+    type: dir
+    file_info:
+      mode: 0755
+
+scripts:
+  postinstall: pkg/debian/scripts/postinstall.sh
+  preremove: pkg/debian/scripts/preremove.sh
+
+deb:
+  compression: zstd
--- a/pkg/debian/scripts/postinstall.sh
+++ b/pkg/debian/scripts/postinstall.sh
@@ -0,0 +1,5 @@
+#!/bin/bash
+# postinstall script for archivebox .deb package
+set -e
+
+/opt/archivebox/install.sh
--- a/pkg/debian/scripts/preremove.sh
+++ b/pkg/debian/scripts/preremove.sh
@@ -0,0 +1,9 @@
+#!/bin/bash
+# preremove script for archivebox .deb package
+set -e
+
+echo "[+] Removing ArchiveBox virtualenv..."
+rm -rf /opt/archivebox/venv
+
+echo "[i] Your ArchiveBox data directories have NOT been removed."
+echo "    Remove them manually if you no longer need them."