Getting started with PrintStash

The normal PrintStash install is Docker Compose. You do not need Python, Node, or a cloud account to run the published images.

Requirements

• Docker and Docker Compose on a linux/amd64 or linux/arm64 host
• About 1 GB of RAM minimum, with 2 GB more comfortable for large meshes
• 1 to 2 CPU cores
• Storage for the container images, database, thumbnails, and your model files

Raspberry Pi 4 and 5, ARM NAS systems, and normal x86 servers are supported. Since v0.12.0 the full image generates STEP and STP previews on ARM as well as amd64. The lite image, which the light Compose file pulls, has no STEP tessellation on any platform.

Install

Download the Compose file and start it. There is no clone to keep and nothing to edit first, because every variable in the file has a working default:

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

docker compose up -d

The Compose file pulls prebuilt images, so nothing builds locally. Open http://localhost:3000 when the containers are healthy.

You do not have to invent a JWT secret. The placeholder in the Compose file is published in the repository, so the API treats it as unusable and generates a real secret on first boot, storing it in its own database. Set VAULT_JWT_SECRET yourself only if you want to hold that value.

Complete first launch

The wizard asks for a setup token before anything else, because the endpoint that creates the first account cannot require a login. With VAULT_SETUP_TOKEN unset, the API generates one per process and writes it to its log:

docker compose logs api | grep "setup token"

From there the wizard creates the first admin account and confirms storage and backup settings. There is no default username or password. Restarting the api container mid-setup invalidates the logged token, so grep again or set VAULT_SETUP_TOKEN for a stable one.

The default install uses SQLite and local disk. Keep that setup for a normal home library. Postgres and S3-compatible storage are available when you have a concrete reason to add them.

Connect a printer

Open Printers -> Add printer and choose the interface your machine exposes:

• Moonraker/Klipper is stable.
• OctoPrint, PrusaLink, Bambu LAN, and Elegoo Centauri are beta.

Support is capability-based. For example, Moonraker supplies measured filament use, while Bambu can upload and start but cannot list files already on the printer. Check the compatibility matrix for the exact column before testing a control action.

Start with status. Then upload a small known-good G-code file without auto-start. Only test start, pause, resume, and cancel when the printer is clear and a mistake cannot damage anything.

Add your first model

Drag an STL, 3MF, OBJ, STEP/STP, G-code, or BGCODE file into the library. You can also use Upload -> From URL for supported Printables, MakerWorld, and Thingiverse pages.

PrintStash will:

• hash the content and detect an identical existing file;
• generate a thumbnail or appropriate preview where supported;
• extract available geometry or slicer metadata;
• create a model record that can hold later revisions and print history.

After the first import

• Put related models into collections and add only the tags you will search.
• Configure Spoolman if it already manages your filament inventory.
• Create and download a tested backup before the first upgrade.
• Add the OrcaSlicer hook when you want new slices to arrive automatically.

The full installation guide covers reverse proxies, optional services, and first-boot troubleshooting in the documentation.