Skip to content
§1

pi2s3 user guide

An AMI for your Raspberry Pi.

pi2s3 images your Raspberry Pi to AWS S3 every night, block by block, while it keeps serving. When the Pi dies, one command restores a complete, bootable Pi to new hardware: the OS, Docker, databases, configuration and keys, with nothing to set up again.

§2

Install

One line on the Pi.

You need Raspberry Pi OS 64-bit (Bookworm or Trixie), an S3 bucket and an IAM user that can write to it. install.sh --iam-policy prints the minimum policy for your bucket.

curl -sL pi2s3.com/install | bash

SSH into the Pi and paste it. It installs partclone, pigz and the AWS CLI, asks for the bucket and region, sets the retention policy and the 2:00 cron job, and runs a dry run. It then offers the first backup, or run it yourself:

bash ~/pi2s3/pi-image-backup.sh --force
§3

How a backup works

Seconds of read only, not an outage.

  • 1. Quiesce the database

    MariaDB and MySQL go read only for under 10 seconds while the disk is flushed. PostgreSQL gets a CHECKPOINT and writes are never blocked. With no database found, Docker stops for the imaging.

  • 2. Save the partition table

    The GPT or MBR layout goes to S3 first, so a restore can recreate it.

  • 3. Image each partition

    partclone reads only the blocks in use, compresses them with pigz and streams them to S3. No local file. A 954 GB NVMe that is 28% full takes about 5 minutes, not the 90 a dd copy takes.

  • 4. Record a manifest

    Host, Pi model, OS, partitions, sizes, duration and a SHA-256 of every image, computed during the upload.

  • 5. Check it

    The files are checked in S3, an availability probe confirms the site stayed up, and a phone notification (ntfy) says how it went.

§4

What is backed up

The whole disk.

  • The OS, kernel and packages
  • Docker, its images and volumes: databases, uploads, everything
  • App configuration and .env files, systemd services and cron jobs
  • SSH authorised keys
  • The partition table and the boot firmware (config.txt, cmdline.txt)

If Docker’s data is on a different disk from the OS, the backup warns you; set BACKUP_EXTRA_DEVICE to image both.

§5

Settings

config.env.

Everything lives in ~/pi2s3/config.env. It holds secrets, so it is never committed. The ones you are most likely to change:

  • S3_BUCKET, S3_REGION

    Where the images go. The only settings you must give.

  • MAX_IMAGES

    How many nightly images to keep. Default 60; older ones are deleted.

  • S3_STORAGE_CLASS

    STANDARD_IA by default, about 40% cheaper for backups.

  • BACKUP_ENCRYPTION_PASSPHRASE

    Encrypts every image with GPG AES-256 before upload. Keep the passphrase somewhere other than the Pi.

  • NTFY_URL, NTFY_LEVEL

    Phone notifications for every backup, or failures only.

  • CRON_SCHEDULE

    2:00 every night by default.

  • AWS_TRANSFER_RATE_LIMIT

    Caps upload speed, for example 2m for 2 MB/s.

  • BACKUP_NICE, BACKUP_MAX_TEMP_C

    Keeps the Pi responsive: lowest priority, and compression pauses at 75°C.

§6

Check your backups

Know they are there.

  • pi-image-backup.sh --list

    Every backup in S3, with size and host.

  • pi-image-backup.sh --verify

    Checks every file in the latest manifest exists in S3 and prints the checksums. --verify=2026-04-15 for a given day.

  • pi-image-backup.sh --dry-run

    Shows what a backup would do without uploading.

  • pi-image-backup.sh --db-check

    Shows which database it found and tests the read only switch, without imaging.

  • pi-image-backup.sh --cost

    S3 space used and the monthly cost.

--list:

  [1] 2026-04-16  4.2G compressed (my-pi-5)
  [2] 2026-04-15  4.1G compressed (my-pi-5)
  [3] 2026-04-14  4.0G compressed (my-pi-5)
  Total: 3 backup(s)

--verify, which also runs after every backup:

  OK  nvme0n1p1-20260415_020045.img.gz (512M)
  OK  nvme0n1p2-20260415_020045.img.gz (3.7G)
  OK  partition-table (1234 bytes)
VERIFY OK. All backup files present in S3.
§7

Restore to a new Pi

From S3 to a booting Pi.

  1. 1Flash Raspberry Pi OS Lite (64-bit) to an SD card with Raspberry Pi Imager and boot the new Pi with the target disk attached.
  2. 2SSH in and run the restore line. It installs the tools, asks for your AWS keys and opens the restore wizard: pick the date and the disk.
  3. 3Each partition streams from S3 straight onto the disk, with its checksum checked on the way.
  4. 4Power off, boot from the restored disk. The root filesystem grows to fill it on first boot.
  5. 5Run the post boot check: configuration, disks, Docker and every container, the tunnel, cron and the database.
curl -sL pi2s3.com/restore | bash

Without prompts, for a given day:

bash ~/pi2s3/pi-image-restore.sh --date 2026-04-13 --device /dev/nvme0n1 --resize --yes

One file or folder, no disk needed (Linux):

bash ~/pi2s3/pi-image-restore.sh --extract /etc --date 2026-04-16

After the first boot:

bash ~/pi2s3/test-recovery.sh --post-boot

The full runbook, recovery USB images, netboot and fleet restores are on pi2s3.com.

§8

Cost

A few dollars a month.

About 3 to 5 GB per image for a 128 GB NVMe a quarter full, in STANDARD_IA:

  • 7 images, about 25 GB

    under $1 a month

  • 30 images, about 120 GB

    about $2 a month

  • 60 images, about 240 GB

    about $3 a month

§9

Problems

If something is not right.

  • The restore says it needs Linux

    sfdisk and partclone do not exist on macOS. Run the restore on the new Pi itself, booted from an SD card.

  • A Pi 5 with NVMe crashes during a restore

    Some Pi 5 and NVMe pairs reset under sustained writes. Add --rate-limit 10m (needs pv) and raise it if it holds.

  • SSH refuses the restored Pi

    It has the old Pi’s host key. Run ssh-keygen -R raspberrypi.local (and the IP address), then connect again.

  • The backup stopped Docker

    It found no database to quiesce. Run --db-check to see why; a native database needs DB_ROOT_PASSWORD in config.env.

  • No backup last night

    The daily stale check sends a notification when none is newer than 25 hours. The failure notification carries the last 10 lines of the log.

  • I lost config.env and used encryption

    The images cannot be read without the passphrase. Store it in a password manager.