Run PrintStash on a Raspberry Pi or ARM NAS

PrintStash publishes Docker images for linux/amd64 and linux/arm64. A Raspberry Pi 4 or 5, an ARM NAS, or an Apple silicon Linux VM can run the same Compose stack as an x86 server. Docker selects the matching image.

The ARM tradeoff that used to define this page is gone. Through v0.11.4, STEP and STP files stored and downloaded on ARM but never got a generated preview. Since v0.12.0 the full image previews them on arm64 too, so what is left to decide on a Pi is memory, storage, and which of the two API images to run.

Pick sensible hardware

The documented minimum is one CPU core and 1 GB of RAM. Use at least 2 GB when the library contains large or dense meshes. Thumbnail generation is the expensive part; normal browsing and search are much lighter once files have been indexed.

Keep the database and application data on reliable storage. A USB SSD is a better long-term home than a small microSD card if the Pi will run continuously. Model files can live in PrintStash’s managed vault or on a mounted NAS folder indexed as a shared volume.

PrintStash limits concurrent mesh rendering and skips previews that do not fit the available memory budget. The file is still indexed when a preview is skipped. This makes a low-memory host usable, although the initial scan will take longer than it would on a faster server.

STEP previews on ARM, and what is still unproven

PrintStash uses OpenCASCADE to tessellate STEP and STP geometry for browser previews. Until v0.12.0 the package behind that had no Linux ARM wheel, so the preview never ran on linux/arm64. Cascadio 0.1.1 ships wheels for both architectures, and v0.12.0 picks it up, so the full image can preview and thumbnail STEP on a Pi.

Read the evidence for what it is before you plan around it. The project verifies this by tessellating a real STEP fixture in an ARM64 image under QEMU in CI, and says plainly that native Raspberry Pi validation on representative 1 GB hardware is still outstanding. That is runtime compatibility, not a performance promise on your hardware.

Two limits apply on any architecture and matter more on a Pi than on a server. Tessellation runs in a disposable child process with a cgroup-aware memory ceiling and a 90 second timeout, which you can raise with VAULT_MESH_STEP_TIMEOUT_SECONDS. A file that exceeds either is stored without geometry or a generated preview instead of taking the API process down with it, and the generic 200 MiB mesh input cap applies before any of that. On a 1 GB Pi, expect a large assembly to be the one that comes back without a picture.

The original CAD file is never changed or rejected either way. STL, 3MF, OBJ, G-code, and BGCODE previews work on ARM as they always have.

Install on a Raspberry Pi

Start with a 64-bit Raspberry Pi OS installation and a current Docker setup. Then fetch the Compose file and bring it up:

mkdir printstash && cd printstash
curl -O https://raw.githubusercontent.com/xiao-villamor/PrintStash/main/docker-compose.yml

docker compose up -d

There is nothing to edit first: every variable in that file has a working default, and the API generates its own signing secret on first boot rather than using the public placeholder. The first run does need a setup token, which the API writes to its log while the vault is unconfigured:

docker compose logs api | grep "setup token"

Open http://<pi-ip>:3000, enter the token, and complete the setup wizard. There is no default admin account.

Check the containers before importing files:

docker compose ps
docker compose logs --tail=100 api

The installation guide has the current requirements and production options.

Full image or lite image

Since v0.12.0 the API ships in two variants, and a thin host is exactly where the choice matters. printstash-api is the default and carries everything. printstash-api-lite drops Chromium, which powers browser-assisted imports of pages that block plain HTTP fetches, and drops the OpenCASCADE tessellation that generates STEP previews. It keeps mesh thumbnailing through NumPy, Pillow, and Trimesh, so STL, 3MF, and OBJ previews are unaffected.

The payoff is size: CI refuses the build unless lite is at least 700 MiB smaller than full, and it also checks that startup does not get slower. On a Pi pulling images over a home connection onto an SD card, that is the difference between a quick upgrade and a long one.

Switching is a Compose file, not a setting. docker-compose.light.yml pulls the lite image, so fetch that file instead of the default one. It also drops the S3 and backup-destination variables, which suits a Pi on SQLite and local disk.

Take lite if your CAD sources are meshes and you import by uploading files or pasting direct links. Stay on full if you keep STEP or STP files and want to see them in the browser, or if you rely on capturing model pages that need a real browser to fetch.

Mount NAS storage carefully

For a NAS folder, mount the share on the Docker host first, then bind that path into the API container. Do not point a shared volume at a path that appears empty because an SMB or NFS mount failed. PrintStash checks for an unexpectedly empty previously indexed volume, but the host mount should still be monitored.

Confirm that the container can see the expected files before starting a scan:

docker compose exec api ls /mnt/nas/3d

Give the API read and write permission only if PrintStash should add uploads or revisions to that folder. Read-only mounts are fine for an archive that should only be indexed. The shared-volume guide covers the Compose mount and write policy in detail.

What to expect from a Pi

A Pi is a good fit for a personal library when import speed is not urgent. Scan a smaller folder first and watch memory use while thumbnails are generated. Dense STL files and large batches will take time, but the UI remains useful after the initial work is cached.

For a large library, several users, or other memory-heavy containers on the same host, use a Pi 5 with more RAM or move the service to a small x86 machine. The files can remain on the NAS either way.