Database-free self-hosted photo/video gallery—mount folders as albums, slideshows, iframes, etc.
651
FolderFrame is a lightweight, self-hosted photo and video gallery that turns folders into albums — no database, no PHP, and no build step.
Mount one or more media libraries and browse them from phones, tablets, desktops, TVs, wall displays, or dedicated digital photo frames. FolderFrame works as a normal interactive gallery, a fullscreen slideshow, a TV/photo-frame display, or an iframe embedded in another site.
FolderFrame is designed around a simple idea: your folders are already your albums.
Project: https://github.com/The-Grog/FolderFrame Website: https://www.folderframe.com/ Live demo: https://demo.folderframe.com/ Deployment repository: https://github.com/The-Grog/FolderFrame-Deployment
Many self-hosted photo applications require a database, indexing service, account system, or proprietary library structure. FolderFrame keeps the media library simple.
Your files stay organized as ordinary folders:
Photos/
├── Family/
│ ├── Birthdays/
│ └── Vacations/
├── Kids/
├── Pets/
└── Travel/
└── OBX 2026/
FolderFrame turns those directories into browsable albums without moving, renaming, or importing your originals.
The official Docker and Unraid deployment can also generate persistent thumbnails, EXIF sidecars, and a media manifest in appdata while keeping the mounted source media read-only.
folderframe.ignore.FolderFrame works well for:
Each display can use its own album, slideshow interval, sort order, and startup mode while sharing the same underlying media.
.jpg
.jpeg
.png
.webp
.gif
.avif
.bmp
.heic
.heif
JPEG, PNG, WebP, GIF, AVIF, and BMP use browser-native image support where available.
HEIC and HEIF are handled natively when supported by the browser. Otherwise FolderFrame can use its bundled heic-to decoder in the full viewer.
Generated WebP thumbnails are recommended for HEIC/HEIF libraries so large grids do not need to convert every visible file.
.mp4
.mov
.webm
.m4v
Video playback still depends on the codecs supported by the browser. A .mp4 or .mov extension alone does not guarantee that the contained video codec can be decoded.
Official Docker deployments can optionally provide FFmpeg-based fallback playback for unsupported videos by streaming H.264/AAC without permanently converting or replacing the original media.
Folders automatically become albums.
FolderFrame provides:
Album covers use a suitable image from the album when available. Generated thumbnails are used automatically when configured.
Create an empty file named:
folderframe.ignore
inside a media folder to exclude that entire folder and its descendants.
FolderFrame also ignores common recycle, trash, metadata, snapshot, temporary, partial-download, backup, and operating-system artifact files.
Open a photo or video to enter the full viewer.
Viewer features include:
Failed media can be skipped automatically during slideshow playback so an unattended display does not stop on one bad file.
TV Mode is intended for televisions, tablets, wall displays, and dedicated photo-frame screens.
Enabling TV Mode:
Browsers generally require a user gesture before entering true fullscreen, so URL or configuration startup can enable the TV behavior but may not always force fullscreen automatically.
Dedicated displays can also use URL options to select a specific album, slideshow interval, source, or startup behavior.
Example:
https://YOUR-FOLDERFRAME/?album=Family&tv=1&interval=10
When the deployment generates EXIF sidecars, FolderFrame can display a Photo Info panel containing supported metadata such as:
GPS display can be disabled independently from metadata generation.
FolderFrame does not embed a map or make map requests merely by opening the Photo Info panel. When valid coordinates are shown, the user may choose to open them in Google Maps.
Original files are not modified.
FolderFrame can operate directly from web-server directory listings, but larger libraries can benefit from generated metadata.
The official Docker and Unraid deployment can maintain a parallel tree of small WebP previews in appdata.
Benefits include:
Missing previews fall back to the original image when practical.
The thumbnail generator skips current previews, detects changed files, and can safely prune old generated WebP cache entries after a complete scan.
For large or deeply nested libraries, FolderFrame can use a generated media manifest instead of having every browser recursively walk directory listings.
This can include:
The index is stored as ordinary static JSON files and served by the web server. FolderFrame remains database-free.
Discovery modes include:
auto — try a published manifest, then fall back to directory listingsdirectory — always use directory listingsmanifest — require the published manifestThis also makes FolderFrame suitable for static hosts such as GitHub Pages and Cloudflare Pages when a manifest is generated before deployment.
FolderFrame is configured with:
folderframe.config.json
Configuration supports multiple named sources plus shared, normal-gallery, and embed-specific defaults.
Common settings include:
{
"sources": [
{
"id": "photos",
"label": "Photos",
"path": "photos/",
"discoveryMode": "auto"
}
],
"defaults": {
"view": "folders",
"sort": "filename",
"interval": 5,
"imageMode": "fit",
"shuffle": false,
"autoRefresh": true,
"tvMode": false,
"autoplay": false,
"controls": true,
"showFilenames": true,
"showDownloadButton": true,
"showCopyButton": true,
"showExifPanel": true,
"showGps": true,
"gridDensity": "comfortable",
"rememberPreferences": true
}
}
Configuration changes are read by the browser and do not require a database migration.
Do not place secrets in folderframe.config.json; it is a publicly served configuration file.
URL parameters make it easy to create bookmarks for specific albums or dedicated displays.
Examples:
?album=Family
?album=Vacations/OBX%202026
?autoplay=1&shuffle=1&interval=10
?tv=1&interval=10
?view=all
?profile=embed
Other URL controls can override source, sorting, image sizing, grid density, Auto Refresh, filename display, controls, EXIF/GPS display, download/copy buttons, and preference handling.
FolderFrame can be embedded in another site with a standard iframe.
<iframe
src="https://YOUR-FOLDERFRAME-SERVER/?profile=embed"
title="Photo and video gallery"
loading="lazy"
allowfullscreen>
</iframe>
The embed profile can be configured separately from the normal gallery.
For a controls-free slideshow, use settings such as:
"embed": {
"controls": false,
"autoplay": true,
"view": "all",
"interval": 10,
"rememberPreferences": false
}
Controls-free playback is useful for kiosks, dashboards, wall displays, and photo frames. Videos are muted in this mode.
The hosting web server must allow framing, and browser autoplay/fullscreen rules still apply.
The official deployment repository contains the supported Docker, Docker Compose, and Unraid setup:
https://github.com/The-Grog/FolderFrame-Deployment
FolderFrame itself only requires static web serving plus either:
The Docker/Unraid deployment adds conveniences such as:
FolderFrame does not require PHP, SQL, or a separate application database.
For multi-library installations, configure multiple media sources and mount each library appropriately on the host.
FolderFrame targets modern desktop and mobile browsers, including current Chrome, Edge, Firefox, and Safari families.
Behavior can vary depending on browser capabilities:
FolderFrame is intended as an online web gallery rather than an offline app.
FolderFrame does not provide its own authentication layer.
If exposing it outside a trusted LAN:
For a local family gallery, limiting access to the trusted LAN is the simplest deployment model.
Download, Copy Image, filename visibility, EXIF display, and GPS display controls are user-interface options — they are not security boundaries.
FolderFrame can also be published without Docker on static hosts when a media manifest is generated ahead of time.
This allows deployment to platforms such as:
Static hosting does not provide live filesystem scanning, so new media must be added to a regenerated and republished manifest.
FolderFrame: https://github.com/The-Grog/FolderFrame
Official Docker / Docker Compose / Unraid deployment: https://github.com/The-Grog/FolderFrame-Deployment
Website: https://www.folderframe.com/
Live demo: https://demo.folderframe.com/
Support development: https://paypal.me/machogrog
FolderFrame application code is available under the MIT License.
The bundled HEIC decoding components have separate LGPL licensing terms. See the repository's THIRD_PARTY_NOTICES.md for details.
FolderFrame does not modify your original media files.
Content type
Image
Digest
sha256:b61d3d165…
Size
109.8 MB
Last updated
3 days ago
docker pull thegrog/folderframe