External Media (Reference Mode)

Reference mode lets PicPeak import photos from an existing folder, such as a studio library or NAS share, without copying the originals into PicPeak’s storage. You can import a batch manually or let an event watch its folder for new photos.

PicPeak stores references to the originals and generates thumbnails for the gallery. The original files stay in place and must remain readable by the backend. Back up the source library separately.

Configuration

EXTERNAL_MEDIA_ROOT is the library path as seen by the backend process. In Docker, this is the container path, not the host path. The folder picker only browses within that root.

Docker Compose

Add an override such as docker-compose.external-media.yml to your existing stack:

services:
  backend:
    environment:
      EXTERNAL_MEDIA_ROOT: /external-media
    volumes:
      - /path/to/your/photo-library:/external-media:ro

Replace the host path on the left with your library. Apply the override with the same base Compose file you normally use; for the production stack:

docker compose -f docker-compose.production.yml -f docker-compose.external-media.yml up -d backend

Keep including the override when you recreate or update the stack. See Docker Configuration.

All-in-one and NAS container UIs

On the all-in-one image, add the same read-only library mount and environment variable to the existing container configuration:

# Additional options for your docker run command
-e EXTERNAL_MEDIA_ROOT=/external-media \
-v /path/to/your/photo-library:/external-media:ro

In a NAS container UI, add /external-media as the container-side volume path, enable read-only access for that mount, and set EXTERNAL_MEDIA_ROOT to /external-media. Keep the existing /data volume for PicPeak’s database, thumbnails and other managed data. The external library is a separate mount.

Reference folders remain local filesystem paths even when STORAGE_BACKEND=s3. A mounted NAS library can therefore be watched on an S3-backed installation too; this is separate from the S3 prefix walker.

Importing photos manually

1. Create or open an event and edit its information.
2. Set Source Mode to Reference external folder, choose an External Folder, and save.
3. Open the event’s Photos tab and select Import from External Folder.
4. Confirm the folder and choose Import from selected folder.

The import includes subfolders and accepts .jpg, .jpeg, .png and .webp files. Hidden files and folders are skipped. Files already imported into the event are skipped on later passes; the existing duplicate-name rules also apply, so use distinct filenames within each photo type.

Wait until your copy has finished before starting a manual import. Automatic watching adds the settling checks described below.

Watch a folder for new files

Watching is off for each event by default. To enable it:

1. Edit the event’s information and select Reference external folder under Source Mode.
2. Choose the folder you want this event to follow.
3. Enable Watch folder for new files, beneath the folder picker, and save.

The saved view shows Folder is watched — new files are imported automatically.

You need permission to edit the event (events.edit) and upload photos (photos.upload) to enable watching or change the folder while watching remains enabled. The screenshots show an admin with those permissions. Without upload permission, an unchecked watch box is disabled; an event editor can still turn watching off or edit unrelated event details. See Roles & Permissions.

When new photos appear

• After enabling or restarting: the backend checks which events should be watched about once a minute. When it starts watching a folder, it immediately begins an import pass for files already there.
• After copying new files: filesystem notifications trigger a scan after a 10-second quiet period by default. Files must also settle for 5 seconds; automatic passes defer files that were recently modified or are still changing and retry them later. A large batch or slow share takes longer than these delays alone.
• If the share sends no notifications: a full scan runs every 15 minutes by default. This catches files copied to NFS/SMB shares by another machine. For more frequent detection, enable polling.

Each pass checks the selected folder and its subfolders, imports new photos and generates thumbnails. If face recognition is enabled, new imports enter the face-processing queue. The gallery does not need to be open for this to happen.

The manual import remains available while watching is on. Only one import for an event runs at a time, including across backend replicas; if another pass is busy, wait for it to finish before using the button again.

Deletions and stopping the watcher

Removing a file from the source folder does not remove its gallery record. This prevents a disconnected mount or folder reorganisation from silently deleting gallery entries. A missing original may still be unavailable for viewing or download; restore the file or mount, or deliberately remove the photo in PicPeak.

Photos deliberately deleted in PicPeak are excluded from subsequent automatic imports for that event and source path, even if the file is still on the share. A manual Import from selected folder can bring those photos back; it clears the exclusion for files it imports. Turning watching off and on does not reset those exclusions.

To stop watching an event, clear Watch folder for new files and save. Existing photos remain in the gallery. Switching to Managed source mode clears the watch setting; archived or inactive events are not watched.

For photos replaced through Lightroom or PicPeak, later scans preserve the replacement rather than adding the referenced original again. See Lightroom round-trip → External media.

NAS shares and polling

Start with the defaults. The 15-minute fallback scan works even when a NAS does not forward filesystem notifications. If you need new files detected sooner on such a share, set:

EXTERNAL_MEDIA_WATCH_POLLING=true
EXTERNAL_MEDIA_WATCH_POLL_INTERVAL_MS=5000

Polling checks file metadata repeatedly and creates more work for large libraries or slow shares. Enable watching only for events still receiving photos. Keep the fallback scan enabled unless you have verified that your mount reliably detects new files.

The updated bundled Compose files forward the standard watcher settings from .env. In a custom Compose file, put them in the backend service’s environment block (or an explicitly loaded env_file); a project .env alone is not automatically passed into a container. For AIO, set the variables on the PicPeak container. Recreate the container after changing environment settings; changing the per-event checkbox only needs a save.

For all options and defaults, see Environment Variables → External-folder watching.

Troubleshooting

Look for [externalMediaWatcher] in the backend logs. Missing folders are retried during the periodic configuration check. Successful automatic passes that add photos also appear in the activity log as external-media-watcher; scans with no new photos do not add activity entries.