stegasoo/rpi/BUILD_IMAGE.md

Stegasoo Pi Image Build Workflow

Note: This guide is for developers building custom Pi images. End users: Just download the pre-built .img.zst from Releases, flash it, and boot. No build process needed.

Quick reference for building a distributable SD card image.

Step 1: Flash Fresh Raspbian

Use rpi-imager with these settings:

• OS: Raspberry Pi OS Lite (64-bit)
• Hostname: stegasoo
• Enable SSH: Yes (password auth)
• Username: admin
• Password: stegasoo
• WiFi: Configure for your network (sanitize script removes it later)

Step 2: Boot & SSH In

# Wait for Pi to boot (~60 seconds), then:
ssh admin@stegasoo.local
# or use IP from router DHCP list

Step 3: Pre-Setup

# Take ownership of /opt (for pyenv, jpegio builds)
sudo chown admin:admin /opt

# Install git and zstd (not included in Lite image)
sudo apt-get update && sudo apt-get install -y git zstd jq

Step 4: Clone Repo

cd /opt
git clone -b 4.1 https://github.com/adlee-was-taken/stegasoo.git stegasoo

Step 5: Copy Pre-built Tarball (from host)

Dev-only asset: This tarball is for building Pi images, not for end users. It's available on Releases for image builders.

# On your host machine:
scp rpi/stegasoo-rpi-runtime-env-arm64.tar.zst admin@stegasoo.local:/opt/stegasoo/rpi/

This tarball contains:

• pyenv with Python 3.12 (pre-compiled for ARM64)
• venv with all dependencies (jpegio, scipy, etc.)

Install time: ~2 minutes (vs 20+ min from source)

Step 6: Run Setup

cd /opt/stegasoo
./rpi/setup.sh  # Detects local tarball, skips download

From-Source Build (optional)

To build without the pre-built tarball:

./rpi/setup.sh --no-prebuilt  # Takes 15-20 minutes

Step 7: Test It Works

sudo systemctl start stegasoo
curl -k https://localhost:5000
# Should return HTML

Step 8: Sanitize for Distribution

# Full sanitize (for final image - removes WiFi, shuts down)
sudo /opt/stegasoo/rpi/sanitize-for-image.sh

# Or soft reset (for testing - keeps WiFi, reboots)
sudo /opt/stegasoo/rpi/sanitize-for-image.sh --soft

This removes:

• WiFi credentials (unless --soft)
• SSH host keys (regenerate on boot)
• SSH authorized keys
• Bash history
• Stegasoo auth database
• Logs and temp files

The script validates all cleanup steps before finishing.

Step 9: Pull the Image

Remove SD card, insert into your Linux machine:

# Find the SD card device (CAREFUL!)
lsblk

# Pull image (auto-resizes to 16GB, compresses with zstd)
sudo ./rpi/pull-image.sh /dev/sdX stegasoo-rpi-4.1.5.img.zst

The script automatically resizes rootfs to 16GB, disables auto-expand, and compresses.

Step 10: Distribute

Upload .img.zst to GitHub Releases.

Users can flash with:

# Option 1: rpi-imager CLI (supports .zst.zip directly)
sudo rpi-imager --cli --disable-verify stegasoo-rpi-*.img.zst.zip /dev/sdX

# Option 2: flash-image.sh (auto-detects SD card, shows progress)
sudo ./rpi/flash-image.sh stegasoo-rpi-*.img.zst.zip

# Option 3: Manual dd
zstdcat stegasoo-rpi-*.img.zst | sudo dd of=/dev/sdX bs=4M status=progress

---

Creating the Pre-built Tarball

After a successful from-source build, create the pre-built tarball for future installs:

# On the Pi after successful setup:
cd ~

# Strip caches and tests from venv (295MB → 208MB)
find /opt/stegasoo/venv/ -type d -name '__pycache__' -exec rm -rf {} + 2>/dev/null
find /opt/stegasoo/venv/ -type d -name 'tests' -exec rm -rf {} + 2>/dev/null
find /opt/stegasoo/venv/ -type d -name 'test' -exec rm -rf {} + 2>/dev/null

# Create venv tarball
cd /opt/stegasoo
tar -cf - venv/ | zstd -19 -T0 > ~/stegasoo-venv.tar.zst

# Create combined tarball (pyenv + venv pointer)
cd ~
tar -cf - .pyenv stegasoo-venv.tar.zst | zstd -19 -T0 > /tmp/stegasoo-rpi-runtime-env-arm64.tar.zst

# Check size (should be ~50-60MB)
ls -lh /tmp/stegasoo-rpi-runtime-env-arm64.tar.zst

Pull to host and upload to GitHub releases:

# On host:
scp admin@stegasoo.local:/tmp/stegasoo-rpi-runtime-env-arm64.tar.zst ./
# Upload to GitHub releases as stegasoo-rpi-runtime-env-arm64.tar.zst

---

Quick Command Summary

# On Pi (after SSH):
sudo chown admin:admin /opt
sudo apt-get update && sudo apt-get install -y git zstd jq
cd /opt && git clone -b 4.1 https://github.com/adlee-was-taken/stegasoo.git stegasoo

# On host (copy tarball):
scp rpi/stegasoo-rpi-runtime-env-arm64.tar.zst admin@stegasoo.local:/opt/stegasoo/rpi/

# On Pi (run setup):
cd /opt/stegasoo && ./rpi/setup.sh
sudo systemctl start stegasoo
curl -k https://localhost:5000
sudo /opt/stegasoo/rpi/sanitize-for-image.sh

# On host (pull image - auto-resizes to 16GB):
sudo ./rpi/pull-image.sh /dev/sdX stegasoo-rpi-4.1.5.img.zst