On this page
Athéna Resident agent on a Raspberry Pi 5

Documentation — Pi guide

Prerequisites, delivered files, rebuilding the PDF and verifying it.

Prerequisites

  • a Raspberry Pi running Debian 13 (trixie) — the guide is written and verified on a Pi 5 B Rev 1.1 (BCM2712 + RP1, 16 GB), non-root user;
  • git, python3, systemd: already present on Raspberry Pi OS Lite;
  • to rebuild the PDF: python3-fpdf (Debian package) and the DejaVu fonts (fonts-dejavu-core);
  • to replay the proofs: ghostscript (gs) and curl.

No sensor, no hardware purchase, no third-party account is needed to apply chapters 1 to 9.

Delivered files

guide.md            the full guide (Markdown, 2,222 lines, 14 chapters)
guide.pdf           the same guide, laid out (36 pages)
build_pdf.py        rebuilds the PDF from the Markdown
verifier_guide.py   checks the guide against the files of the layer
verifier_pdf.py     checks the PDF against the Markdown

Rebuild and verify

python3 build_pdf.py        # guide.md → guide.pdf (fpdf2, DejaVu fonts)
python3 verifier_guide.py   # chapters, cited paths, excerpts, programs
python3 verifier_pdf.py     # chapters, parts, appendices, 119 code blocks

verifier_guide.py only reads the guide and the files of the layer: it runs no command and changes nothing. It tells four kinds of blocks apart — literal copy, partial excerpt, composed command, dated output — and flags any labelled block that cannot be found in a real file.

verifier_pdf.py extracts the PDF text with gs -sDEVICE=txtwrite, then compares: the 14 chapters, the 4 parts, the 3 appendices and every code block must be there, with a consistent page count.

How to proceed

The chapter 14 checklist is ordered and copyable: look before installing (temperature, throttling, disk, ports), install the tools, create the tree, write the .gitignore before the first commit, install the units with User= and an absolute path, verify with systemctl and curl, run the first backup and the tested restore, add the off-machine copy, run the tests, then wire the backlog and the cron.

The guide never asks you to trust an example: each chapter lists its source files and the command that lets you re-check what is claimed.

What remains manual

  • restarting a Python service after editing its file (chapter 5): code is not reloaded on the fly;
  • copying the bundle off the machine, and decrypting it if you encrypt;
  • automating the restore test (tests/test_sauvegarde.py does not exist yet) and encrypting the bundle (sys/sauvegarde_chiffree.py neither).