Immich Folio

Turn your Immich albums into a public photography portfolio — without ever exposing your Immich server to the internet.

A self-hosted portfolio powered by Immich. It acts as a secure reverse proxy between your visitors and your private Immich instance: your Immich server stays on your local network, completely invisible to the outside world, while your albums are published as a gallery you control.

Latest: v0.22.0 — unlisted albums with their own links, a ready-made Docker image for amd64 and arm64, and one vocabulary across the admin panel. → Release notes

Features

• Albums as pages — group Immich albums into subpages, standalone albums and a hero, all defined in content/gallery.yaml or built in the admin panel
• Grids and layouts — masonry, uniform, showcase, filmstrip, editorial flow and justified rows, with six hero layouts and per-page overrides
• Fullscreen lightbox — keyboard and swipe navigation, EXIF panel, and opt-in zoom to full resolution (guide)
• Twelve theme presets — each in dark and light, with fine control over colours, fonts and photo frames (guide)
• Journal and photo essays — long-form stories with drafts, passwords and a map (guide)
• Client work — password-protected pages, proofing with favourites, private proofing links and originals as a ZIP
• Admin panel — visual page builder, journal studio, settings editor, backups and diagnostics at /admin (guide)
• Private by design — your Immich URL and API key never reach the browser, asset IDs are encrypted into opaque tokens, and only the albums you list are reachable
• Six interface languages, cookieless analytics and dynamic social preview images

→ All features, with screenshots

Quick start

You need an Immich server (3.0 or newer) and Node.js 20+, or just Docker. Immich setup covers the API key and its permissions.

git clone https://github.com/ralksta/immich-folio.git
cd immich-folio
npm install
npm run dev

Open http://localhost:3000/install and let the setup wizard connect you to Immich. It needs a token from the server log, which is printed on first access (First-run setup).

Prefer to configure by hand?

The wizard writes the same files you would write yourself, so the manual route remains fully supported:

cp .env.local.example .env.local
# Edit .env.local with your Immich server URL and API key

cp content/gallery.yaml.example content/gallery.yaml
# Edit gallery.yaml with your album UUIDs

npm run dev

Something not coming up? npm run doctor checks the configuration from the terminal, with no running app and no admin password needed (Config Doctor).

Docker

No checkout needed: every release is published as ghcr.io/ralksta/immich-folio (amd64 and arm64). Put this in an empty folder as docker-compose.yml:

services:
  lightbox:
    image: ghcr.io/ralksta/immich-folio:latest
    container_name: immich-folio
    restart: unless-stopped
    ports:
      - '7211:7211'
    volumes:
      - ./content:/app/content

Run docker compose up -d, then open http://localhost:7211/install; the setup token is in docker compose logs lightbox. The content/ volume must be read-write. See Deployment for image tags, updating, building from source, the health check, reverse proxy and CDN mode.

Documentation

Guide	Covers
Immich setup	Version, API key permissions, full-size images
Deployment	First-run wizard, environment variables, Docker, reverse proxy, CDN
Gallery structure	gallery.yaml: hero, albums, subpages, per-album options, content pages
Site settings	settings.yaml: grid, language, navigation, watermark, SEO, footer, about
Gallery features	Passwords, proofing, photo zoom, original downloads
Security	Rate limits, trusted proxies, token revocation
Theming	Presets, colours, fonts, hero styles
Journal & photo essays	File format, blocks, drafts, Journal Studio
Admin panel	Page builder, settings, analytics, backups
Features	The full feature list with screenshots

Release history is in the CHANGELOG and the GitHub releases. Security fixes ship in normal releases, so running the latest release is the recommended baseline.

Contributing

Built with Next.js 16, React 19, TypeScript and plain CSS. Maintained by @ralksta; see CONTRIBUTORS.md for everyone who helped. Contributions are welcome: start with CONTRIBUTING.md, and open pull requests against dev.

License

MIT License. Free to use and modify for the Immich community.