## Summary
This PR adds automated build and release workflows for Debian (.deb) and
Homebrew packages, replacing the legacy PPA-based distribution model. It
includes build scripts, packaging configurations, and updated GitHub
Actions workflows to generate and publish packages on release.
## Related issues
Improves package distribution and installation experience for Linux and
macOS users.
## Changes these areas
- [x] Internal architecture
- [x] Feature behavior (installation methods)
## Details
### New Build Infrastructure
**Debian Packages:**
- Added `bin/build_deb.sh` - Builds .deb packages using nfpm with
support for multiple architectures (amd64, arm64)
- Added `pkg/debian/nfpm.yaml` - nfpm configuration defining package
metadata, dependencies, and contents
- Added `pkg/debian/archivebox` - Wrapper script that activates the
virtualenv and runs archivebox CLI
- Added `pkg/debian/install.sh` - Post-install setup script that creates
virtualenv and installs dependencies
- Added `pkg/debian/archivebox.service` - Systemd service file for
running archivebox as a service
- Added `pkg/debian/scripts/postinstall.sh` and `preremove.sh` - Package
lifecycle scripts
- Added `bin/release_deb.sh` - Uploads built .deb packages to GitHub
Releases
**Homebrew Packages:**
- Added `bin/build_brew.sh` - Generates Homebrew formula using
homebrew-pypi-poet, auto-populating dependencies and checksums
- Added `brew_dist/archivebox.rb` - Homebrew formula template with
virtualenv support and service definition
- Added `bin/release_brew.sh` - Pushes updated formula to the
homebrew-archivebox tap repository
### Updated Workflows
**`.github/workflows/debian.yml`:**
- Changed trigger from `push` to `release: [published]` for
release-based builds
- Updated to Ubuntu 24.04 and added multi-architecture build matrix
(amd64, arm64)
- Replaced legacy stdeb-based build with nfpm
- Added artifact upload and GitHub Release integration
- Added test job that installs and verifies the .deb package
**`.github/workflows/homebrew.yml`:**
- Changed trigger from `push` to `release: [published]`
- Replaced bottle building with formula generation using
homebrew-pypi-poet
- Added artifact upload and automatic push to homebrew-archivebox tap
- Added test job that installs and verifies the formula
### Updated Installation Instructions
- Modified `bin/setup.sh` to download and install from GitHub Releases
.deb instead of PPA
- Updated `README.md` to document the new .deb installation method
- Updated `bin/build.sh` and `bin/release.sh` to include new build and
release scripts
## Test Plan
- GitHub Actions workflows will test package builds on release events
- Debian workflow includes automated test job that installs the .deb and
verifies `archivebox version`
- Homebrew workflow includes automated test job that installs the
formula and verifies the CLI
- Manual testing can verify installation via: `sudo apt install
./dist/archivebox*.deb` or `brew install archivebox` (after tap setup)
https://claude.ai/code/session_01Vx1EsNrNySgsc8Y67dGzCn
<!-- devin-review-badge-begin -->
---
<a href="https://app.devin.ai/review/archivebox/archivebox/pull/1771"
target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-open-in-devin-review-dark.svg?v=1">
<img
src="https://static.devin.ai/assets/gh-open-in-devin-review-light.svg?v=1"
alt="Open with Devin">
</picture>
</a>
<!-- devin-review-badge-end -->
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds automated Debian (.deb) and Homebrew packaging with CI + release
orchestration, replacing the PPA and making installs via `apt` and
`brew` straightforward on Linux and macOS. Packages are thin wrappers
around pip to reduce dependencies; also fixes Docker release tags when
run via the orchestrator.
- **New Features**
- Debian `.deb` via `nfpm` (amd64/arm64): venv at
`/opt/archivebox/venv`, `/usr/bin/archivebox` wrapper (exports PATH)
used by the `systemd` service (no `--setup`); postinstall creates the
`archivebox` user, pins to the package version, enforces Python ≥ 3.13
in `install.sh`, and restarts the service after upgrades. Package
depends only on `python3`/`pip`/`venv`, recommends `git`/`curl`/`wget`.
CI pre-seeds the venv with a local wheel, runs init/status/add on native
`amd64`/`arm64`, and uploads to Releases only after tests pass; release
upload now fails loudly if the Release is missing when triggered by a
release event (skips gracefully on manual runs). `preremove.sh` stops
the service during upgrades to avoid stale venv binaries, and only
disables/removes the venv on full removal.
- Homebrew formula auto-generated with `homebrew-pypi-poet`: virtualenv
install with a single dependency on `python@3.13`, a `post_install` that
initializes in `var/archivebox` with `DATA_DIR` set, and a `caveats`
message showing the data directory. CI generates from a local sdist on
push and from PyPI on release, tests on macOS and Linuxbrew, then pushes
to the `homebrew-archivebox` tap.
- GitHub Actions: `release.yml` orchestrates `pip` → `.deb`/brew →
docker; Docker workflow treats `workflow_call` as a release so
semver/latest tags are published. Tests hardened (e.g., `tests/out`),
README `.deb` install detects arch via `dpkg` and fetches the latest
version via the GitHub API.
- **Migration**
- Ubuntu/Debian: install from Releases (`sudo apt install
/tmp/archivebox.deb`), replacing the PPA.
- macOS/Linuxbrew: `brew tap archivebox/archivebox && brew install
archivebox`.
<sup>Written for commit 36b4055304.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
The post_install initializes var/archivebox as the data directory,
but users need to know where it is for subsequent commands. The
caveats block is shown after brew install/upgrade to guide users.
https://claude.ai/code/session_01Vx1EsNrNySgsc8Y67dGzCn
preremove.sh stops the service during upgrades (to avoid stale venv
binaries), but postinstall.sh wasn't restarting it. Now postinstall
checks if the service was enabled and restarts it after the venv is
rebuilt, so upgrades don't leave a previously running service down.
https://claude.ai/code/session_01Vx1EsNrNySgsc8Y67dGzCn
- preremove.sh: Stop the systemd service during upgrades (not just
remove/purge) so the running process doesn't use stale venv binaries
while postinstall replaces them. Only disable + remove venv on full
removal.
- debian.yml: Fail loudly when release lookup fails during a release
event (exit 1), but still skip gracefully for workflow_dispatch
manual testing (exit 0). Prevents silently broken .deb publication.
- archivebox.rb + build_brew.sh + homebrew.yml: Add post_install that
initializes ArchiveBox in var/archivebox with DATA_DIR set, using
correct Homebrew system() syntax (no env hash as first arg).
https://claude.ai/code/session_01Vx1EsNrNySgsc8Y67dGzCn
docker.yml uses github.event_name to decide between full release tags
(semver, latest) vs CI-only tags (branch, sha). When release.yml calls
it via `uses:`, the child sees event_name='workflow_call' which was
hitting the non-release path. Now workflow_call is treated the same as
workflow_dispatch so published releases get proper Docker tags.
https://claude.ai/code/session_01Vx1EsNrNySgsc8Y67dGzCn
- install.sh: Replace awk float comparison with integer major/minor check
so Python 3.9 is correctly rejected as < 3.13
- nfpm.yaml: Add git/curl/wget as recommends so users have basic archiving
tools out of the box without needing `archivebox install`
- debian.yml: Restore git/curl/wget in CI smoke test to match what the
package recommends, instead of relying on runner preinstalls
- debian.yml: Guard release upload to skip gracefully when no GitHub
Release exists (fixes workflow_dispatch failures)
https://claude.ai/code/session_01Vx1EsNrNySgsc8Y67dGzCn
The release job was duplicating ~70 lines of PyPI fetching + formula
generation that build_brew.sh already handles. Now it just calls
./bin/build_brew.sh. Also merged the two Linux-only brew setup steps.
https://claude.ai/code/session_01Vx1EsNrNySgsc8Y67dGzCn
Remove all non-essential dependencies from both package formats.
The .deb now only depends on python3, pip, and venv. The brew
formula only depends on python@3.13. All other runtime deps
(node, chrome, yt-dlp, wget, ripgrep, etc.) are installed
on-demand by `archivebox install` at runtime.
Removed from brew formula:
- 6 depends_on entries (node, git, wget, curl, ripgrep, yt-dlp)
- on_linux block (pkg-config, openssl, libffi)
- post_install hook (was running archivebox install)
- service block (users run archivebox server directly)
Removed from .deb:
- 6 depends entries (nodejs, npm, git, wget, curl, ripgrep)
- recommends section (yt-dlp, ffmpeg, chromium)
Net: -126 lines across packaging files.
https://claude.ai/code/session_01Vx1EsNrNySgsc8Y67dGzCn
- systemd service: use /usr/bin/archivebox wrapper (exports venv PATH
for bundled tools like yt-dlp) instead of direct venv binary
- install.sh: prefer python3.13, fail early with clear error if < 3.13,
add comment clarifying the manual (unpinned) fallback behavior
- debian.yml release job: fall back to pyproject.toml version when
github.event.release.tag_name is empty (workflow_dispatch path)
- nfpm.yaml: clarify that install.sh enforces the real >= 3.13 constraint
- CI pre-seed step: expanded comment explaining why we pre-seed with
python3.13 and how it relates to real installs
https://claude.ai/code/session_01Vx1EsNrNySgsc8Y67dGzCn
- Pin cache-apt-pkgs-action to commit SHA for supply-chain safety
- Fix Homebrew post_install to use with_env block instead of env hash
in system() call (idiomatic Homebrew pattern)
- Add clarifying comments to service file, preremove.sh, and nfpm.yaml
explaining user/group creation, directory ownership, and upgrade handling
https://claude.ai/code/session_01Vx1EsNrNySgsc8Y67dGzCn
- Move .deb upload to GitHub Release into a separate job that runs after tests pass
- Fix workflow_call event propagation so release jobs run when called from release.yml
- Fix setup.sh post-install verification to check `which archivebox` first (works for brew/deb)
- Fix README.md: detect architecture with dpkg instead of hardcoding amd64
- Fix README.md: remove --setup flag from apt install instructions
https://claude.ai/code/session_01Vx1EsNrNySgsc8Y67dGzCn
- Remove --setup flag from systemd service and CI (not valid in 0.9.x)
- Remove release triggers from debian/homebrew workflows (handled by release.yml)
- Fix brew post_install to set DATA_DIR so it initializes in var/archivebox
- Add PATH export to deb wrapper script for bundled console scripts
- Remove pip install fallback in install.sh (strict version pinning)
- Guard preremove.sh cleanup to only run on remove/purge, not upgrade
- Initialize SDIST_URL/SDIST_SHA256 in build_brew.sh (nounset safety)
- Pin awalsh128/cache-apt-pkgs-action to v1.6.0 (supply chain safety)
https://claude.ai/code/session_01Vx1EsNrNySgsc8Y67dGzCn
- test-parallel.yml: mkdir -p tests/out before pytest --basetemp
(fixes FileNotFoundError in chrome test fixture)
- debian.yml: fix archivebox add command (--parser url_list removed
in 0.9.x), remove || true so failures are caught
- setup.sh: revert apt section to always use pip install, not .deb
https://claude.ai/code/session_01Vx1EsNrNySgsc8Y67dGzCn
- homebrew.yml: Build local sdist, generate formula with file:// URL and
real resource stanzas via homebrew-pypi-poet, run full
`brew install --build-from-source` on both macOS and Linux (Linuxbrew)
- debian.yml: Pre-seed venv with local wheel before dpkg install so
postinstall succeeds even for unreleased versions; test init/status/add
- Both workflows trigger on push (path-filtered) and release
- Release job generates formula with PyPI URL and pushes to tap
https://claude.ai/code/session_01Vx1EsNrNySgsc8Y67dGzCn
- Fix debian.yml: pin nfpm version, add permissions, improve test job
with user creation, init test, and status check
- Fix homebrew.yml: use PyPI JSON API (macOS-compatible, no grep -oP),
wait for PyPI availability on release, use generated formula not template,
add Linux (Linuxbrew) test job alongside macOS
- Add release.yml orchestrator: pip → deb + brew + docker in order
- Add workflow_call triggers to pip.yml and docker.yml
- Fix build_brew.sh: replace grep -oP with Python-based PyPI API,
add on_linux deps (pkg-config, openssl, libffi)
- Fix setup.sh: use GitHub API to find correct .deb download URL
(filename includes version number)
- Fix postinstall.sh: create archivebox system user, pin version from
package, check for systemd before daemon-reload
- Fix preremove.sh: stop service before removal, check for systemd
- Fix install.sh: fallback to latest if pinned version not on PyPI
- Add on_linux deps to brew formula for Linuxbrew support
- Tested: .deb builds, installs, creates user, runs archivebox init
https://claude.ai/code/session_01Vx1EsNrNySgsc8Y67dGzCn
## Summary
This PR updates the README, Dockerfile, and docker-compose configuration
to reflect changes for the v0.9.0 release, including:
- Replacing `init --setup` with `init --install` command throughout
documentation
- Updating minimum Python version requirement from 3.10 to 3.13
- Updating minimum Node version requirement from 18 to 22
- Updating uv version from 0.5 to 0.6
- Simplifying installation instructions (removing explicit yt-dlp and
playwright install steps)
- Updating tech stack documentation (Django 5.1 → 6.0, Huey → custom
orchestrator, pdm → uv)
- Removing deprecated configuration options (SAVE_ARCHIVEDOTORG,
YTDLP_MAX_SIZE, individual USER_AGENT variables)
- Consolidating USER_AGENT configuration into a single option
- Updating database filename from index.sqlite to index.sqlite3
- Removing localhost subdomain references (admin.archivebox.localhost →
localhost)
- Simplifying development server commands (manage runserver → server)
- Fixing typos and minor documentation improvements
## Related issues
Roadmap goal: v0.9.0 release
## Changes these areas
- [x] Configuration options
- [x] Command line interface
- [x] Internal architecture
## Test Plan
Documentation changes only. Verify that:
- All command examples in README execute correctly with the new `init
--install` syntax
- Docker build completes successfully with updated base image and uv
version
- docker-compose configuration is valid and services start correctly
- Development setup instructions work as documented
https://claude.ai/code/session_01X2H7XLawCzLGnrxMArXtVZ
<!-- devin-review-badge-begin -->
---
<a href="https://app.devin.ai/review/archivebox/archivebox/pull/1770"
target="_blank">
<picture>
<source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-open-in-devin-review-dark.svg?v=1">
<img
src="https://static.devin.ai/assets/gh-open-in-devin-review-light.svg?v=1"
alt="Open with Devin">
</picture>
</a>
<!-- devin-review-badge-end -->
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Update docs, Docker image, and compose config for v0.9.0. Switch to
`init --install`, require Python 3.13/Node 22, upgrade `uv` to 0.6,
align examples/tech stack, restore subdomain routing with
`*.archivebox.localhost`, and fix Docker build/run issues.
- **Migration**
- Use `archivebox init --install` everywhere; dev commands use `server`
(not `manage runserver`).
- Require Python >= 3.13 and Node >= 22; base image and examples updated
(`python:3.13-slim`, `archivebox>=0.9.0`).
- Config: consolidate to `USER_AGENT`; deprecate `SAVE_ARCHIVEDOTORG`,
`SAVE_FAVICON`, and `YTDLP_MAX_SIZE`; keep `SAVE_WGET`/`SAVE_DOM` via
legacy aliases; DB is `index.sqlite3`.
- Restore subdomain routing: `LISTEN_HOST=archivebox.localhost:8000`,
`CSRF_TRUSTED_ORIGINS=http://admin.archivebox.localhost:8000`. Tech
stack: Django 6.0 + `daphne`, custom orchestrator, built with `uv`.
- **Bug Fixes**
- Fix NodeSource GPG key import, multi-arch build flag spacing,
Playwright install line, and a missing `\` that broke Docker builds.
- Re-enable `archivebox version` during image build and run it as
non-root via `gosu`; entrypoint handles unset `PUID` when blocking root.
- Restore HEALTHCHECK to `admin.archivebox.localhost`; compose comments
use `docker compose` and open `web.archivebox.localhost:8000`.
<sup>Written for commit 37b8a011db.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
- Add missing backslash on line 383 that caused Docker build parse failure
(the linter removed the \ continuation character, breaking the RUN instruction)
- Use gosu to run archivebox version as the archivebox user since
ArchiveBox refuses to run as root
https://claude.ai/code/session_01X2H7XLawCzLGnrxMArXtVZ
- Restore LISTEN_HOST=archivebox.localhost:8000 and
CSRF_TRUSTED_ORIGINS=http://admin.archivebox.localhost:8000 in
docker-compose.yml (subdomain routing is core to ArchiveBox architecture)
- Restore HEALTHCHECK URL to admin.archivebox.localhost in Dockerfile
- Restore SAVE_WGET=False SAVE_DOM=False in README security section
(old SAVE_* env vars still work via x-aliases in config.json)
- Revert dev setup docs to use ./bin/lock_pkgs.sh instead of bare uv sync
- Fix docker-compose.yml open URL to web.archivebox.localhost:8000
https://claude.ai/code/session_01X2H7XLawCzLGnrxMArXtVZ
- 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
