3027706d49
The shrinking is only for faster image downloads. After flashing, the image should auto-expand to fill the SD card. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
187 lines
4.9 KiB
Markdown
187 lines
4.9 KiB
Markdown
# 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](https://github.com/adlee-was-taken/stegasoo/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
|
|
|
|
```bash
|
|
# Wait for Pi to boot (~60 seconds), then:
|
|
ssh admin@stegasoo.local
|
|
# or use IP from router DHCP list
|
|
```
|
|
|
|
## Step 3: Pre-Setup
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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](https://github.com/adlee-was-taken/stegasoo/releases) for image builders.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
cd /opt/stegasoo
|
|
./rpi/setup.sh # Detects local tarball, skips download
|
|
```
|
|
|
|
### From-Source Build (optional)
|
|
|
|
To build without the pre-built tarball:
|
|
```bash
|
|
./rpi/setup.sh --no-prebuilt # Takes 15-20 minutes
|
|
```
|
|
|
|
## Step 7: Test It Works
|
|
|
|
```bash
|
|
sudo systemctl start stegasoo
|
|
curl -k https://localhost:5000
|
|
# Should return HTML
|
|
```
|
|
|
|
## Step 8: Sanitize for Distribution
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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 (for smaller download), preserves auto-expand, and compresses.
|
|
|
|
## Step 10: Distribute
|
|
|
|
Upload `.img.zst` to GitHub Releases.
|
|
|
|
Users can flash with:
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
```
|