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.
- Installinstall
- What is backed upcovered
- Settingssettings
- Check your backupscheck
- Restore to a new Pirestore
- Costcost
- Problemsproblems
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
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.
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.
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.
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.
From S3 to a booting Pi.
- 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.
- 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.
- 3Each partition streams from S3 straight onto the disk, with its checksum checked on the way.
- 4Power off, boot from the restored disk. The root filesystem grows to fill it on first boot.
- 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.
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
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.