An offline emergency library, built for Raspberry Pi. The Pi broadcasts its own open Wi-Fi, a QR code joins it, and the phone's captive-portal sheet opens a start page with ranked search across Kiwix archives (Wikipedia, WikiMed, iFixit, Stack Exchange, Army doctrine, Gutenberg and more) plus an offline US map. No internet, app or account is needed once it is built.
Search returns result cards (source, section title, the matching passage, a link to open it on the box). Nothing is generated, so nothing is made up. Every archive is split into sections and searched with a full-text index (field-manual PDFs are converted to searchable text first), and a small on-device reranker (MiniLM) puts the best passages on top.
This repository holds the code and instructions. It does not contain any archive: you download
each one from its source (CONTENT-SOURCES.md).
This is an educational DIY project, provided as is with no warranty (see LICENSE). The reference
content it serves is not medical, legal or professional advice and may be out of date or wrong; in
an emergency call your local emergency number if you can. Not affiliated with prepperdisk.com,
Kiwix, or any content source. You are responsible for the licenses of the content you load and
give away (CONTENT-SOURCES.md, THIRD-PARTY-NOTICES.md).
On the build machine you also need: uv, sqlite3, rsync, jq, coreutils (numfmt, sha256sum), qrencode, and ImageMagick with the DejaVu fonts (for the label).
| part | notes |
|---|---|
| Raspberry Pi 5, 8 GB | A Pi 4 works for testing, slowly. |
| Official Pi 5 case with fan, or the official active cooler | Searching keeps the CPU busy; a bare board throttles. |
| 1 TB NVMe SSD on an M.2 HAT, or a 1 TB USB 3 SSD | The Pi 5 boots from either. The library does not fit on a microSD card (a 32 GB+ microSD is enough for a Pi 4 test with a small library). |
| Official 27 W USB-C supply | The Pi 5 needs 5 V at 5 A for full USB current. |
| Optional: RTC battery | The Pi has no internet time and no clock backup without it. |
The onboard Wi-Fi handles a handful of phones; expect a ceiling of about eight.
Build time depends on the library: the core set is about 65 GB of downloads, the full set with Gutenberg about 300 GB.
Needs Docker, uv, curl, and about 3 GB of disk for this minimal run.
cp .env.example .env # DATA_DIR=./data
mkdir -p data/index data/maps
./fetch-library.sh data/zim wikipedia_en_medicine # WikiMed, about 2 GB, checksum-verified
./fetch-reranker.sh data/reranker
cd section-index && ./build-index.sh ../data/zim ../data/index/sections.db && cd ..
docker compose up -d --build
Open http://127.0.0.1:6042/ and search "how do I treat a burn". docker compose down stops
it. The Maps tile needs data/maps/us.pmtiles (below). The optional model: put
qwen2.5-1.5b-instruct-q4_k_m.gguf (from https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct-GGUF)
in data/models/ and run docker compose --profile phrasing up.
Tests: cd ask-service && uv run pytest (likewise assemble, section-index, battery, image).
- Build the image (on a native aarch64 Linux host; a Pi works):
image/build.sh. It writes~/piper-image/out/piper-<date>.img.xzand its sha256. Details:image/README.md. - Flash it to the SSD with Raspberry Pi Imager ("Use custom image") or
dd(image/README.md). Optional: name the network withimage/set-network-name.sh(defaultpiper). Outside the US, write your two-letter Wi-Fi country code tostate/wifi-countryon the data partition (defaultUS). Raspberry Pi OS keeps the radio off until a country is set. - Download the archives and verify them.
./fetch-library.sh ~/library/zim core extradownloads each file and checks its published.sha256; a truncated archive serves nothing../fetch-library.sh --listshows every file and group. ReadCONTENT-SOURCES.mdfirst: iFixit is non-commercial, and several sources are deliberately left out. - Assemble the PDF archives (Army doctrine, USDA canning):
./fetch-library.sh ~/library-src army canning, then followassemble/README.md; write the resulting ZIMs into~/library/zim/. It needspoppler-utils, andtesseractfor scanned pages. - Build the search index:
section-index/build-index.sh ~/library/zim ~/library/index/sections.db. Wikipedia takes hours; the build is resumable. - Maps (optional): install the
pmtilesCLI (https://github.com/protomaps/go-pmtiles/releases), copy the URL of the latest build from https://maps.protomaps.com/builds, thenpmtiles extract <build-url> ~/library/maps/us.pmtiles --bbox=-125,24,-66.5,49.5(the contiguous US; adjust the box for Alaska and Hawaii). Verify the download with the BLAKE3 hash the builds page lists (b3sum). - Load the library onto the SSD's data partition (mounted, or over SSH once the box is up):
image/load-library.sh ~/library /path/to/mounted/prepperdata. It copies with checksums and writes the manifest the services wait for. - Print the label:
./make-labels.sh piper http://10.42.0.1/(needsqrencodeand ImageMagick). One image with a Wi-Fi join QR code, a start-page QR code, and the name and address as text. - First boot: plug the SSD-equipped Pi in. No screen is needed. After 20 to 40 seconds of boot it reboots once by itself (it is switching the root filesystem to read-only), and is ready about a minute after power-on.
- Join: scan the left QR code. The phone's sign-in sheet should open the start page. If not, scan
the right code or open
http://10.42.0.1/orhttp://prepper.local.
Check the finished box against image/hardware-checklist.md. To measure search quality, run the
question battery against a running service: cd battery && uv run python run.py --url http://127.0.0.1:6042.
Archive file names are pinned. ask-service/app/data/*.json, ask-service/app/search.py and
ask-service/static/index.html name them, so a source link or tile only works for the files in
fetch-library.sh. A tile or shortcut for an archive you did not load simply 404s.
Wikipedia refreshes roughly every six months (the no-images build more often), medical archives
yearly. To update: download the newer files (https://download.kiwix.org/zim/), verify their
checksums, replace the old name with the new one everywhere
(grep -rl OLD . | xargs sed -i s/OLD/NEW/), rebuild the index, and run load-library.sh again
(then delete the old files from the box). Re-read CONTENT-SOURCES.md for any source whose license
changed.
- Archive will not open or serves nothing: the download was truncated. Re-run
fetch-library.sh(it resumes) and watch for a checksum failure. - Search says "Nothing in the library matched" for everything, or the service will not start:
sections.dbis in WAL journal mode, which a read-only mount cannot open. Rebuild withsection-index/build-index.sh, which leaves it in the right mode. - Services do not start on the Pi:
/data/library/manifest.jsonis missing. Runload-library.sh. - The Pi throttles or drops out: it needs the fan or active cooler; never run a bare board.
- SD card corruption after power loss: boot from the SSD. After first boot the root filesystem is read-only, so pulling the plug is safe.
- Phones drop off: the onboard radio supports about eight clients.
- Wrong time: there is no internet time and no clock backup. Fit the RTC battery.
- The phone does not open the start page by itself: use the second QR code or the address.
| directory | what it is |
|---|---|
ask-service/ |
the search service and start page (FastAPI), static map page |
section-index/ |
builds the section-level search index (sections.db) |
assemble/ |
turns PDF collections into searchable ZIMs that also carry the original PDFs |
image/ |
the Raspberry Pi image builder, first-boot logic, load script, hardware checklist |
battery/ |
the fixed question set and its scorer |
docs/captive-portal.md |
how phones detect a captive portal |
Piper is free. If it helped you build a box for your family, you can buy me a coffee:
MIT for this repository's own code and docs (LICENSE). Third-party software and assets:
THIRD-PARTY-NOTICES.md. Archive content: CONTENT-SOURCES.md.
The Piper name and fox logo (docs/piper-logo.png) are not covered by the MIT license:
copyright 2026 Jared Behunin, all rights reserved. You may show the logo when linking to or
describing this project.
