Raspberry Pi deployment

This profile runs the single-container QSfera server on a 64-bit Raspberry Pi OS and persists configuration and user data outside the container. It expects a separate reverse proxy for a browser-trusted TLS certificate; by default port 9200 is therefore published only on 127.0.0.1.

Requirements

uname -m must report aarch64 or arm64.
Docker Engine with the Compose plugin must be installed.
The selected QSfera image tag or digest must contain linux/arm64.
The configuration and data directories must be on persistent storage and writable by UID/GID 1000:1000, which is the non-root user in the image.

For an external disk mounted at /mnt/qsfera, create the directories with:

sudo install -d -o 1000 -g 1000 -m 0750 /mnt/qsfera/config /mnt/qsfera/data
findmnt /mnt/qsfera

findmnt must show the expected external filesystem before the service starts. This prevents an unavailable disk from silently placing data on the Pi's root filesystem.

Configuration

cd Server/deployments/raspberry-pi
cp .env.example .env
chmod 600 .env

Fill every empty value in .env. The Compose file deliberately has no default for the image, public URL, admin password, persistent paths or memory limit. docker compose config fails when any of these values is empty.

Choose QSFERA_MEMORY_LIMIT from measurements on the target Pi:

QSFERA_MEMORY_LIMIT = total RAM - OS reserve - other services reserve

Use free -h for total/current host memory and docker stats for the other containers. Leave enough headroom for the kernel, filesystem cache and reverse proxy. QSfera's Go runtime then derives its own default GOMEMLIMIT from the container limit with a 0.9 ratio.

Keep QSFERA_BIND_IP=127.0.0.1 when the reverse proxy runs on the same Pi. Set it to a reachable interface only when access to port 9200 is protected by an equivalent network and TLS design.

Start and verify

sh ./smoke-test.sh
docker compose ps

The smoke test validates the Compose file, starts the service and waits for the container health check. Its default 180-second startup budget can be changed with SMOKE_TIMEOUT_SECONDS.

Backup

The backup script stops QSfera, archives both persistent directories, writes a SHA-256 checksum and starts the service again:

sh ./backup.sh /mnt/backups/qsfera

Copy the resulting .tar.gz and .sha256 files to storage that is independent of the Pi and its data disk.

Restore

Restore replaces the current configuration and data. Check the selected archive and its checksum first, then run:

RESTORE_CONFIRM=restore sh ./restore.sh /mnt/backups/qsfera/qsfera-TIMESTAMP.tar.gz
sh ./smoke-test.sh

The restore script verifies the checksum when the matching .sha256 file is present and stops the service during replacement. It starts QSfera only after a successful extraction; after an error the service remains stopped so a partial data set is never served automatically.

3.2 KiB Raw Blame History