foldergram/foldergram: Self-Hosted Instagram-Style Gallery for Local Folders

foldergram/foldergram: Self-Hosted Instagram-Style Gallery for Local Folders

Developers and self-hosters who manage large local media collections face a persistent friction: filesystem browsers are functional but uninspiring, while cloud-based photo services demand uploads, subscriptions, and surrender of data control. The gap between "files on disk" and "pleasant browsing experience" remains surprisingly wide. foldergram/foldergram addresses this directly—it's a self-hosted web application that transforms local folders into an Instagram-inspired photo and video gallery, with no cloud dependency, no upload pipeline, and no multi-user account complexity. This article examines what foldergram/foldergram actually delivers, how it works under the hood, and whether it fits your stack.

What is foldergram/foldergram?

foldergram/foldergram is an open-source, self-hosted gallery application maintained under the GNU Affero General Public License v3.0. As of its last commit on 2026-06-06, the project has accumulated 505 GitHub stars and 26 forks—modest but healthy traction for a focused tool in the personal media space. The codebase is primarily TypeScript, structured as a pnpm monorepo with a Node.js 22 backend and Vue 3 frontend.

The project's core premise is filesystem-native: it reads from a configured GALLERY_ROOT, indexes supported media into SQLite, generates thumbnails and previews, and serves a Progressive Web App with familiar Instagram-style patterns—feed scrolling, profile grids, stories-style highlights, and a dedicated Reels queue for video. There's no ingestion step beyond placing files in folders. No account creation for visitors. No remote API calls.

This design choice matters for several audiences. Privacy-conscious users keep data entirely local. Developers with existing media workflows—perhaps generated by scripts, synced from devices, or organized by project—gain immediate browsability without restructuring. DevOps^{↗ Bright Coding Blog} engineers running home infrastructure get a containerized, low-maintenance service with clear environment-based configuration. The project explicitly excludes features common to social platforms: no comments, no messaging, no notifications, no cloud sync, no multi-user accounts in the traditional sense. It's a deliberate scope boundary that shapes what foldergram/foldergram is and isn't.

Key Features

Instagram-Inspired Interface. The UI replicates patterns users already understand: a home feed with Recent, Rediscover, and Random modes; app folders functioning as profile pages with post grids; a top rail showing Moments (when capture-date coverage is strong) or Highlights (when it isn't); and a /reels route with video-only queue configurable to Recommended, Recent, or Random ordering.

Filesystem-Native Indexing. Any non-hidden folder directly containing supported media becomes an indexed "App Folder." Nested folders with media become separate App Folders with parent-prefixed routes (e.g., /folder/parent-nested). Files placed directly in GALLERY_ROOT are ignored—this prevents root clutter from polluting the index.

Derivative Generation with Flexible Timing. Thumbnails and previews can generate eagerly during scans or lazily on first request. Generated derivatives now store under stable asset-key shards rather than mirroring source folder structure, enabling folder moves without re-generation. The system distinguishes discovery, derivative migration, and derivative generation phases with separate progress reporting.

Access Control Modes. Three session tiers exist: admin (full access), viewer (browse and shared likes, no settings or destructive actions), and public anonymous (browse-only with browser-local favorites). Configuration happens through the Settings UI, not environment variables—though PUBLIC_DEMO_MODE can make all API mutations read-only for safe public deployments.

Supported Media Formats. Images: .jpg, .jpeg, .png, .webp, .gif, .avif. Videos: .mp4, .mov, .m4v, .webm, .mkv. Animated images retain animation in post viewer and feed cards; thumbnail surfaces remain static. Animated AVIF sequences generate static WebP thumbnails and animated WebP previews.

Progressive Web App. Includes web app manifest and production service worker registration for installable, offline-capable client experience.

Use Cases

Personal Media Archive on NAS or Home Server. Users with years of photos organized by event, trip, or date on network storage can point Foldergram's GALLERY_ROOT at existing folders without reorganization. The Docker^{↗ Bright Coding Blog} deployment path makes this particularly accessible for NAS platforms with container support.

Development and Design Asset Browsing. Teams or individuals managing large collections of screenshots, mockups, reference imagery, or video clips in version-controlled or script-generated folder structures gain instant visual browseability. The feed and grid patterns suit rapid visual scanning better than filesystem thumbnails.

Client Presentation Gallery. Photographers or videographers can generate derivative previews from project folders and present work through a polished, familiar interface. The optional public demo mode with read-only API protection allows safe sharing without risk of accidental modification.

Local-First Workflow Integration. Developers building media pipelines—perhaps generating frames from ML inference, rendering outputs, or processing drone imagery—can append Foldergram as a visualization layer. The SQLite metadata and derivative caching mean repeated browsing doesn't re-process source files.

Privacy-Preserving Family Sharing. For users avoiding cloud photo services due to privacy concerns or data residency requirements, Foldergram provides multi-device access within a local network without external dependencies.

Installation & Setup

The recommended path uses the pre-built GitHub Container Registry (GHCR) image with Docker Compose.

Create a directory and download the Compose file:

mkdir foldergram
cd foldergram
wget -O docker-compose.yml https://raw.githubusercontent.com/foldergram/foldergram/main/docker-compose.yml

Create your gallery structure and add media:

mkdir -p data/gallery/example-album
# Move photos or videos into data/gallery/example-album/

Start the container:

docker compose up -d

Container startup automatically runs pending SQLite migrations before opening the library database. The application listens on http://localhost:4141.

The shipped docker-compose.yml includes IMAGE_DETAIL_SOURCE: preview and DERIVATIVE_MODE: eager. Modify these before starting if you prefer lazy derivatives or original-backed detail pages. For folder exclusions, add under the environment: block:

GALLERY_EXCLUDED_FOLDERS: "@eaDir,thumbnails,Archive/cache"

For a read-only public demo, add:

PUBLIC_DEMO_MODE: "1"
CSRF_TRUSTED_ORIGINS: "https://your-public-domain.com"

For local builds from source instead of GHCR:

docker compose -f docker-compose.yml -f docker-compose.local.yml up -d --build

Source Installation

Requirements: Node.js 22, pnpm (preferred) or npm, plus ffmpeg and ffprobe for video support outside Docker.

git clone https://github.com/foldergram/foldergram.git
cd foldergram
cp .env.example .env
pnpm install
pnpm dev

Development ports: client prefers localhost:4141 (auto-fallback to 4144), API on 4140, docs on 4145. For production builds: pnpm build then pnpm start.

Real Code Examples

The README provides configuration through environment variables. Here's the documented default storage layout:

data/
  ├─ gallery/       # Original source media
  ├─ db/
  │   └─ gallery.sqlite
  ├─ thumbnails/    # Generated thumbnails and poster images, sharded by asset key
  └─ previews/      # Generated previews, sharded by asset key

This structure separates concerns: GALLERY_ROOT needs only read access, while DB_DIR, THUMBNAILS_DIR, and PREVIEWS_DIR require write access. The sharded storage under asset keys rather than mirrored paths enables Foldergram to track media identity across folder moves without regenerating derivatives.

The Docker Compose environment configuration for common customizations:

environment:
  IMAGE_DETAIL_SOURCE: preview    # or 'original' to stream source files
  DERIVATIVE_MODE: eager          # or 'lazy' for on-demand generation
  GALLERY_EXCLUDED_FOLDERS: "@eaDir,thumbnails"
  PUBLIC_DEMO_MODE: "0"

These flags operate independently. IMAGE_DETAIL_SOURCE affects only image detail pages; videos always use preview playback. DERIVATIVE_MODE=eager front-loads processing during scans; lazy defers until first request. The GALLERY_EXCLUDED_FOLDERS syntax supports bare names (matching anywhere in the tree) or slash-containing paths (exact relative matches under GALLERY_ROOT).

For public demo deployments, the documented .env configuration:

NODE_ENV=production
PUBLIC_DEMO_MODE=1
CSRF_TRUSTED_ORIGINS=https://foldergram.intentdeep.com

PUBLIC_DEMO_MODE=1 blocks all POST, PUT, PATCH, and DELETE requests under /api. CSRF_TRUSTED_ORIGINS is required when the browser-visible origin differs from the upstream Node host, such as behind reverse proxies or HTTPS terminators. The live demo at foldergram.intentdeep.com runs this configuration.

Advanced Usage & Best Practices

Derivative Strategy Selection. Eager mode suits predictable, complete browsing experiences—first scan takes longer, but all surfaces are immediately responsive. Lazy mode reduces initial scan time and storage pressure for large archives where only a subset receives regular attention. Consider lazy mode for archives exceeding tens of thousands of items where full pre-generation is prohibitively slow.

Folder Organization for Clean Indexing. Since Foldergram creates App Folders only for directories directly containing supported media, intentional folder nesting can separate logical collections. A structure like 2024/Trip-Japan/Photos and 2024/Trip-Japan/Videos yields two App Folders (Trip-Japan-Photos, Trip-Japan-Videos in routing) rather than one merged collection—design your hierarchy accordingly.

Migration Path from Legacy Versions. The asset-key sharding introduced in recent versions migrates existing libraries in-place on the next full scan. The system preserves existing paths for files that already exist and repairs surviving legacy derivatives where possible. Plan a full scan after upgrades rather than expecting immediate migration on first boot.

Access Mode Selection. The viewer tier with separate password suits trusted family or team members who need like functionality without administrative risk. Public mode with admin unlock from the "More" menu balances convenience for personal use with protected settings access. Avoid PUBLIC_DEMO_MODE for personal instances unless you genuinely need read-only presentation.

Comparison with Alternatives

Foldergram occupies a narrower niche: developers and technical users who want immediate, attractive browseability of existing folder structures without feature bloat or ingestion ceremonies. Photoprism and Immich serve users seeking comprehensive management; Piwigo suits those wanting extensive customization. Foldergram trades depth for immediacy and aesthetic familiarity.

FAQ

Does Foldergram require uploading photos to a cloud service? No. All media remains local; the application reads from configured filesystem paths only.

What Node.js version is required? Node.js 22 LTS, as specified in the project's badges and documentation.

Can multiple users have separate accounts? No. The current implementation supports admin, viewer, and public anonymous sessions, but not multi-user accounts with separate libraries.

Is the AGPL v3 license compatible with commercial use? Yes, with the copyleft requirement that derivative works distributed to others must also be under AGPL v3. Internal use without distribution does not trigger this obligation.

Does video support require additional dependencies? Yes, ffmpeg and ffprobe are required for source installations. The Docker image includes them internally.

Can I run Foldergram without Docker? Yes, via pnpm install and pnpm dev or pnpm start after building, though Docker is the recommended path.

What happens if I move or rename source folders? The asset-key sharding preserves media identity; existing thumbnails and previews are reused after rescanning rather than regenerated.

Conclusion

foldergram/foldergram solves a specific, well-defined problem with architectural clarity: turn existing local folder structures into an immediately browsable, aesthetically familiar gallery without ingestion steps, cloud dependencies, or account complexity. It's best suited for developers, self-hosters, and privacy-conscious users who value filesystem-native workflows and want visual browseability without restructuring years of organized media.

The project is actively maintained with recent commits, clear Docker deployment paths, and thoughtful technical decisions around derivative storage and migration. It deliberately excludes social features and multi-user complexity—limitations that are also strengths for its target audience.

Explore the repository, try the live demo, and evaluate whether its scope matches your needs: https://github.com/foldergram/foldergram.

For broader context on self-hosted media infrastructure, see our coverage of [INTERNAL_LINK: modern-self-hosted-storage-solutions].