Install FolderFrame on Unraid

FolderFrame is available in Unraid Community Apps and uses the tested stable image channel.

The optional video fallback tries native playback first, then streams unsupported video through FFmpeg without creating converted files in your media or appdata. Software CPU encoding is supported; GPU acceleration is not implemented. It is limited to two jobs by default and supports sequential playback without arbitrary seeking. In Add another Path, Port, Variable, Label or Device, choose Variable to set FOLDERFRAME_VIDEO_TRANSCODE=false, FOLDERFRAME_TRANSCODE_JOBS=1, or FOLDERFRAME_TRANSCODE_THREADS=2 as needed. See transcoding details.

Install from Community Apps

1. Open the Apps tab and search for FolderFrame.
2. Select FolderFrame.
3. Choose an existing dedicated Media Folder containing only media intended for this gallery. The template mounts it at /media/Library read-only.
4. Keep the default Appdata Configuration path or choose another persistent directory.
5. Choose an unused Web Port.
6. Keep Generate Thumbnails and Persistent Media Manifest set to true for faster large galleries.
7. Optionally set any other FolderFrame defaults. Leave an override blank to use folderframe.config.json.
8. Click Apply, then open the FolderFrame WebUI.

The media library is mounted at /media/Library read-only. The /media parent stays unmounted so Docker can create additional sibling mounts. Configuration, generated thumbnails, and the persistent manifest are stored separately under /config.

Additional media folders

FolderFrame can combine multiple host directories into one gallery. Each added directory appears as a top-level album and is included in the same thumbnail and manifest scan.

1. Open the Unraid Docker tab, click the FolderFrame icon, and choose Edit.
2. Click Add another Path, Port, Variable, Label or Device.
3. Set Config Type to Path and give it a descriptive name, such as Archive Photos.
4. Select the additional host directory in Host Path. For an SMB share, mount it on Unraid first and select its Linux path, commonly below /mnt/remotes/; Windows UNC paths cannot be used directly by the container.
5. Set Container Path to a unique sibling below /media/, such as /media/Archive. Do not use /media itself or reuse another mapping's path.
6. Set Access Mode to Read Only.
7. Click Add, then Apply to recreate the container with the new mount.

Repeat these steps for as many folders as needed, using a different container path each time—for example /media/Family, /media/Archive, and /media/Scans. Folder names beneath /media/ become the album names shown in FolderFrame. The existing photos/ source and generated thumbnail/manifest configuration do not need to change.

Migrate an existing /media mount

Older FolderFrame containers mounted the primary host directory directly at /media. That layout cannot support a second read-only library because Docker cannot create /media/AnotherLibrary beneath a read-only bind mount.

1. Stop the container, then open Edit in the Unraid Docker tab.
2. Change the existing Media Folder container path from /media to /media/Library. Keep its host path and Read Only access mode unchanged.
3. Add any additional libraries at distinct sibling paths such as /media/Archive or /media/Scans; never mount /media itself.
4. Apply the change and open FolderFrame. The primary library now appears as the top-level Library album.
5. The manifest and thumbnail worker rebuild paths automatically. To reclaim no-longer-referenced generated previews after confirming the new gallery, stop the container and delete only /config/thumbnails/ and /config/folderframe-data/; do not delete original media. Start the container to generate fresh caches.

Persistent configuration

On first start, the container creates:

/mnt/user/appdata/folderframe/folderframe.config.json
/mnt/user/appdata/folderframe/thumbnails/
/mnt/user/appdata/folderframe/folderframe-data/library.json
/mnt/user/appdata/folderframe/folderframe-data/library.d/
/mnt/user/appdata/folderframe/folderframe-data/exif.d/

Edit that file for the complete FolderFrame configuration. It remains outside the image and survives container updates. The file is served to browsers, so do not put passwords, tokens, private filesystem paths, or other secrets in it.

The Unraid fields below provide optional overrides for common settings:

Blank override fields defer to the persistent JSON file. Explicit overrides are applied to a generated runtime copy; the persistent JSON file is never rewritten.

Persistent thumbnails and manifest

The CA template enables both by default. They share one scan interval and are independently configurable:

The initial scan of a very large or Immich-backed library can take time. The gallery remains available. Later scans reuse unchanged manifest directory records; changes appear on the next scan and stale chunks are cleaned up. HEIC/HEIF support is included, while corrupt files are logged. Originals remain read-only.

Missing or invalid manifests trigger a logged full rebuild. Helper errors are retried at the next interval and do not stop Caddy. scanCache is separate and not required.

To force a rebuild, stop the container, delete only /mnt/user/appdata/folderframe/folderframe-data/library.json and library.d/, then restart. Deleting all appdata also deletes custom configuration and thumbnails.

The worker records successful preview source signatures in /mnt/user/appdata/folderframe/folderframe-data/thumbnail-cache.json. It prunes only generated orphan .webp previews after a complete media discovery; mount or stat errors retain uncertain previews. A path with changed size or nanosecond mtime is regenerated rather than reusing a possibly unrelated preview. The first scan after upgrading may reconcile unsigned existing previews. Media mounts stay read-only and originals are never modified.

FolderFrame resolves startup settings in this order: packaged defaults, persistent JSON, explicit container overrides, saved browser preferences, then URL parameters. If a changed default appears to have no effect, set Remember Browser Preferences to false, clear that browser's saved FolderFrame preferences, or test with ?remember=0.

Existing installations

Existing containers created before persistent configuration was added continue to run with packaged defaults. To customize them persistently, edit the container and add:

The default JSON file is created after the container starts. Existing containers might not automatically gain newer optional environment fields; add them manually or reinstall from the current Community Apps template if needed.

Local template installation

For development or template testing, copy the XML into Unraid's user-template directory:

mkdir -p /boot/config/plugins/dockerMan/templates-user
cp /path/to/FolderFrame-Deployment/templates/folderframe.xml \
  /boot/config/plugins/dockerMan/templates-user/my-folderframe.xml

In the Unraid WebGUI, open Docker > Add Container, select folderframe from the Template list, and review every field before applying.

Verify the installation

After applying the template:

1. Open WebUI from the container menu.
2. Confirm /mnt/user/appdata/folderframe/folderframe.config.json was created.
3. Confirm /mnt/user/appdata/folderframe/thumbnails begins receiving WebP files.
4. Confirm /mnt/user/appdata/folderframe/folderframe-data/library.json, library.d/, and (for images with usable EXIF) exif.d/ are created.
5. Confirm nested folders and images appear while generation is still running.
6. Change one container override, apply the edit, and verify it changes the startup default.
7. Restart the container and confirm the configuration, thumbnails, and media return.
8. Edit the container and verify every media mapping shows Read Only, uses a unique sibling path below /media/, and that nothing is mounted at /media itself.

Updating

The template uses ghcr.io/the-grog/folderframe-deployment:stable. Use Docker > Check for Updates, review the FolderFrame release notes, and update when ready. Unraid recreates the container while preserving the external media and appdata directories.

For rollback, edit the Repository field to a known version tag such as ghcr.io/the-grog/folderframe-deployment:v0.6.3, then Apply.

Security

FolderFrame has no built-in authentication or TLS. Anyone who can reach it can browse and download mounted media and read the served configuration. Keep it on a trusted network unless a separate access layer provides authentication and TLS. Never mount an entire share, repository, secrets, private files, or symlinks to private locations.

Manual Refresh

Manual Refresh defaults to true when the persistent manifest is enabled. Clicking Refresh in the gallery requests the same incremental worker used by the schedule, then loads the published result when it completes. Set the field to false to keep scheduled scans but disable browser-triggered scans. Anyone who can reach an unprotected WebUI can request work; use the same proxy authentication for the whole FolderFrame origin.