Packaging & Installation

dvb-WarpPool ships in multiple formats. The release pipeline (.github/workflows/release.yml, executed by the self-hosted Forgejo runner) builds the Linux + Docker artifacts in parallel on every v* tag and signs them with the project Cosign key (cosign.pub in the repo root).

macOS and Windows are not built by CI — there are no macOS/Windows runners on the forge. The macOS .dmg + tarballs are produced per release on a Mac with packaging/macos/build-macos-release.sh and attached manually (which also means SHA256SUMS gets regenerated over the full asset set and re-signed — see §8 of docs/ci-forgejo-porting.md in the repository; that note is not part of this handbook). The Windows .msi is paused.

Update paths: After the initial install via one of the formats below, you can apply updates in two ways:

1. Package manager (apt/dnf/docker pull/Umbrel app updater) — classic, idempotent, controlled
2. Built-in auto-update since Phase 8 — the admin UI shows an update banner; one click runs download + sha256 verify + optional cosign verify + atomic_swap + systemd hint. See Auto-Update for the workflow.

Overview

Linux .deb (Debian / Ubuntu / Mint)

# download from the release page on git.warppool.org:
wget https://git.warppool.org/dvb-projekt/dvb-WarpPool/releases/download/v1.24.0/dvb-warppool_1.24.0-1_amd64.deb
sudo apt install ./dvb-warppool_1.24.0-1_amd64.deb

# first-run wizard (Bitcoin Core RPC, pool profile, payout address):
sudo dvb-warppool-setup

# start the daemon:
sudo systemctl enable --now dvb-warppool

# UI: http://localhost:18334

What the postinst does:

• creates the system user warppool
• creates /var/lib/dvb-warppool/ (data, mode 0700, owner warppool) and /var/log/dvb-warppool/
• chgrp warppool /etc/dvb-warppool so the setup wizard can atomically write into it via sudo
• systemctl daemon-reload

Logs: journalctl -u dvb-warppool -f

Linux .rpm (Fedora / RHEL / openSUSE)

sudo dnf install ./dvb-warppool-1.24.0-1.x86_64.rpm
sudo dvb-warppool-setup
sudo systemctl enable --now dvb-warppool

post_install_script does the same as the .deb postinst (system user, directories, daemon-reload).

Linux AppImage (portable, no-root)

chmod +x dvb-WarpPool-1.24.0-x86_64.AppImage
./dvb-WarpPool-1.24.0-x86_64.AppImage

Also available as an aarch64 AppImage for ARM boards (Raspberry Pi 5, Pine64, Rock-Pi):

chmod +x dvb-WarpPool-1.24.0-aarch64.AppImage
./dvb-WarpPool-1.24.0-aarch64.AppImage

The first launch opens the setup wizard if no ~/.config/dvb-warppool/config.toml exists. After that the daemon starts directly and the UI is reachable at http://localhost:18334.

Raspberry Pi 5 (Raspberry Pi OS / Ubuntu 24.04 for arm64)

dvb-WarpPool runs very well on the Pi 5 — the Cortex-A76 cores have significantly better single-thread performance than the Pi 4 (relevant for Stratum connection handling and Bitcoin RPC). 8 GB RAM is enough for the gross (Large) profile with a few hundred workers; with 16 GB, enterprise is realistic.

Fastest path: .deb package

# Raspberry Pi OS / Ubuntu / Debian for arm64:
wget https://git.warppool.org/dvb-projekt/dvb-WarpPool/releases/download/v1.24.0/dvb-warppool_1.24.0-1_arm64.deb
sudo apt install ./dvb-warppool_1.24.0-1_arm64.deb
sudo dvb-warppool-setup
sudo systemctl enable --now dvb-warppool

Alternative: Docker (with Bitcoin Core sidecar)

docker run -d --name warppool \
  --restart unless-stopped \
  -p 3333:3333 -p 18334:18334 \
  -v /etc/dvb-warppool:/config:ro \
  -v warppool-data:/data \
  git.warppool.org/dvb-projekt/dvb-warppool:1.24.0

Multi-arch image — Docker automatically pulls the arm64 variant on the Pi.

Storage recommendation

• NVMe HAT (e.g. Pimoroni NVMe Base, Geekworm X1003) strongly recommended. The pool DB (SQLite WAL + shares_raw eviction every 60s) puts heavy pressure on SD cards — a typical SD only lasts months under pool load, an NVMe lasts years.
• If using SD: high-quality industrial-grade SD (e.g. Sandisk Industrial, Western Digital Endurance) — no cheap consumer SDs.
• A USB-3 SSD is the middle-ground option if no NVMe HAT is available.

Bitcoin Core on the same Pi

8 GB RAM is enough for both (pool + Bitcoin Core with prune=10000), as long as the mempool isn’t extremely full. 16 GB is more comfortable. Bitcoin Core on its own needs 5–7 GB under normal load.

With a separate Bitcoin Core host (e.g. an Umbrel / Start9 on the LAN), 4 GB RAM is also enough on the Pi 5 for the pool alone.

hwdetect detects the Pi automatically

The setup wizard reads /proc/device-tree/model and identifies the Pi model. On the Pi 5, Environment::RaspberryPi is set, and the profile recommendation system offers gross (Large) as the highest recommended tier for that hardware — a recommendation, not an enforced cap — plus the NVMe storage hint as Severity::Info.

Pi 4 works too

The Pi 4 is tested, but the Pi 5 is recommended (higher per-core performance). Pi 3 and Pi Zero only make sense for klein (Small) profiles and are not intended for production use.

macOS .dmg

⚠ Unsigned — Gatekeeper warning on first launch. Notarization with an Apple Developer ID is planned for Phase B.

1. Open the .dmg → drag dvb-WarpPool.app into the Applications folder
2. Right-click → “Open” → confirm “Open” (Gatekeeper override)
3. The first launch opens a Terminal with the setup wizard
4. Subsequent launches: double-clicking the app opens the UI in the browser automatically

State: ~/Library/Application Support/dvb-WarpPool/ (config + data + logs)

Windows .msi

⏸ Releases currently ship no .msi. There has been no Windows build runner since the move to the project’s own forge, so the release pipeline skips this job (.github/workflows/release.yml, job 6). The WiX packaging (packaging/windows/main.wxs) is still maintained and the artifact returns as soon as a Windows runner exists. Until then, build it yourself with cargo wix on a Windows machine, or run the pool via Docker or the Linux packages. The steps below apply to an .msi you built yourself.

⚠ Unsigned — SmartScreen warning on first launch. Code-signing with an EV certificate is planned for Phase B.

1. Double-click the .msi → “More info” → “Run anyway”
2. Installs to C:\Program Files\dvb-WarpPool\
3. Start the setup wizard manually: Start menu → dvb-warppool-setup
4. Daemon via Task Scheduler or Command Prompt: dvb-warppool-daemon.exe --config C:\ProgramData\dvb-warppool\config.toml

Docker

docker run -d --name warppool \
  -p 3333:3333 -p 18334:18334 \
  -v /etc/dvb-warppool:/config:ro \
  -v warppool-data:/data \
  git.warppool.org/dvb-projekt/dvb-warppool:1.24.0 \
  --config /config/config.toml --data-dir /data

First run: the admin account needs /config writable — once

The first visit to /admin asks you to create an admin account, and the daemon writes those credentials to secrets.toml next to your config.toml. With /config mounted read-only (as above) that write fails and the UI reports that the secrets file is not writable.

The write is atomic (temp file + rename), so it needs the directory writable — bind-mounting only secrets.toml read-write is not enough. Two ways round it:

a) Open a window for the first run, then close it. Drop :ro (and make the directory writable by the container’s uid if you run with user:), create the account, then restore :ro and recreate the container. Only the one-time bootstrap needs this: everything the admin UI stores afterwards — donation addresses, tab toggles, suppressed warnings — lives in the database under --data-dir, so read-only config is fine from then on.

b) Pre-provision secrets.toml. If it already carries admin_username, admin_password_hash and jwt_secret, no bootstrap is needed and /config can stay read-only from the start.

If you run the container as a non-root user: — note that the daemon only reads secrets.toml, but it must be able to read it. Leave the file owned by that uid with mode 600; a root-owned 600 file locks the daemon out.

Multi-arch (amd64 + arm64) is selected automatically — no --platform needed.

Signature verification (Cosign)

Every release includes SHA256SUMS plus a Cosign signature bundle (SHA256SUMS.bundle), verified against the project cosign key (cosign.pub in the repo root). Cosign 3.x writes the bundle format rather than a bare .sig, so pass --bundle:

cosign verify-blob \
  --key cosign.pub \
  --bundle SHA256SUMS.bundle \
  SHA256SUMS
# must print: Verified OK

# then against the individual files:
sha256sum --check SHA256SUMS

GitHub-era releases (<= v1.15.0) were keyless-OIDC-signed and shipped a SHA256SUMS.sig — those artifacts are gone with the account, see the repo history for the steps they used.

Build provenance

Releases ≤ v1.15.0 (GitHub era) shipped SLSA-3 provenance via slsa-github-generator (*.intoto.jsonl in the release assets). That generator is GitHub-OIDC-bound and does not run on the self-hosted forge, so newer releases rely on the project Cosign signature (above) plus reproducible builds (rebuild byte-for-byte and compare SHA256SUMS, see reproducible builds) for supply-chain assurance instead.

SBOM (SPDX)

sbom.spdx.json in every release lists all crates with their versions and licenses (via anchore/sbom-action). Usable with syft / grype for vulnerability audits.

Phase B — open loose ends

• macOS Notarization: xcrun notarytool submit with a Developer ID certificate + Apple ID + app-specific password. Since the .dmg is currently built manually on a Mac (no macOS runner), notarization would be a local step there; if a macOS runner is ever added, APPLE_ID, APPLE_TEAM_ID and APPLE_NOTARY_PASSWORD would go into the Forgejo Actions secrets.
• Windows code-signing: signtool sign with an EV certificate. Azure Code Sign is an alternative for CI-friendly token-based signing.
• Logo / icon design: Currently only a 1×1 placeholder in the AppImage; macOS and Windows have no icon. Once the design is finalized (see ROADMAP.md), it needs to be placed under packaging/{appimage,macos,windows}/.