Mirror your NAS folder into PrintStash without moving files

You do not need to upload a 400 GB NAS library into PrintStash. Mount the folder into the API container and add it as a shared volume. PrintStash indexes the files in place.

Getting the files onto the NAS in the first place is a separate problem, and syncing STL files between a PC and a NAS covers the sync tools plus the specific ways they interact with a scan.

How shared volumes work

The folder remains the source of truth. PrintStash stores the database record, parsed metadata, and generated thumbnail while leaving the original model or G-code file at its existing path.

In mirror mode, subfolders become nested collections. A file at props/helmets/mando.stl appears under props, then helmets. Single-collection mode puts everything from that shared volume into one selected collection instead.

A scan reconciles the index with disk. New files are indexed. Changed files are hashed and parsed again. Files removed from disk move to PrintStash trash.

Write-back works in the other direction. New uploads and revisions for a model in a writable shared volume are added to that folder. Use a read-only Docker mount if you want indexing without write-back.

The safety rules

PrintStash follows a few conservative rules around external files:

• Write-back adds a new file with collision-safe naming. It does not overwrite an existing file.
• Permanently deleting a linked model removes PrintStash records but skips the external bytes.
• Removing a shared volume moves its indexed records to trash and leaves the mounted folder alone.

An unmounted NAS is the dangerous case. Linux may leave an empty mount point behind, which can look like every file was deleted. PrintStash aborts without changing the index when the root is missing, unreadable, or empty while it still has indexed files. Remount the share and run the scan again.

Scheduling and real-time watching

Each shared volume has a preset schedule, a custom cron expression, or manual-only mode. Scheduled scans remain useful even when watching is enabled because they catch events missed during a restart.

Local filesystems can use native events for faster updates. NFS and SMB mounts normally do not deliver those events, so automatic mode falls back to the schedule. Forced watching uses periodic stat checks and costs more work than native events.

Mount the path into Docker

The path in PrintStash is inside the api container. Add a Compose override instead of editing the shipped file:

services:
  api:
    volumes:
      - /mnt/nas/3d:/mnt/nas/3d

Apply it with docker compose up -d, then check the container view:

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

If that command cannot see the files, PrintStash cannot see them either.

One practical note on memory

A dense mesh can consume much more memory than its file size suggests. PrintStash estimates mesh cost before rendering and skips the preview when the configured or memory-aware limit is too low. The file still enters the index.

Keep the default single render job on a small host. Lower the mesh limits if the container shares a Raspberry Pi or NAS with other memory-heavy services. The large-mesh guide explains the settings and what a skipped preview means.