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 -mmust reportaarch64orarm64.- 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.