immich-folio/docs/admin-panel.md

Admin Panel

Immich Folio includes a built-in visual admin panel at /admin that lets you manage your gallery structure, journal entries and site settings without editing YAML files by hand.

Contents:

• Enabling the Admin Panel
• Layout
• Pages
• Journal
• Settings
• Analytics
• Album & Asset Pickers
• Security
• Backups
• Docker Usage

Enabling the Admin Panel

Set ADMIN_PASSWORD in your .env.local (or Docker environment):

ADMIN_PASSWORD=your-secure-admin-password

Then navigate to http://your-site/admin. The panel is completely disabled if no password is set — it won't even render the login page.

The setup wizard can set the password instead, storing it as an scrypt hash in content/install.json. An ADMIN_PASSWORD environment variable takes precedence if both are present.

Important

The admin password is separate from any album or subpage passwords. It controls access to the entire gallery configuration.

Layout

Each area has its own URL, so a section can be bookmarked and the browser's back button works as expected:

Tab	URL	Writes to
Pages	/admin/pages	content/gallery.yaml
Journal	/admin/journal	content/journal/<slug>.md
Settings	/admin/settings	content/settings.yaml, content/about.md
Proofing	/admin/proofing	content/proofing.json
Analytics	/admin/analytics	nothing — read-only
Diagnostics	/admin/diagnostics	nothing — read-only
Help	/admin/help	nothing — reference only

Unsaved changes raise a save bar pinned to the bottom of the viewport, so the Save button is reachable without scrolling back up. Saving applies immediately — no server restart.

Overview

/admin opens on the overview: what needs attention (unread messages, doctor warnings and errors, each linking to where it is fixed), the site at a glance (published pages, hero photos, journal entries and drafts, views in the last seven days) and a few quick actions. Navigation sits in a sidebar grouped into Content, Visitors, Site and System; View site, Backups, Reload and Sign out are at its foot. See the UX concept for where this is going.

Pages

The page builder has two columns: on the left the whole structure (home page hero, every subpage with its cover, state and album count, standalone albums), always visible and drag-sortable; on the right the selected entry, edited in place. A subpage's panel switches between Edit and Live preview in its header. A visual tree of your gallery structure. Each item opens a slide-over drawer with its settings.

Hero Images

Immich asset UUIDs for the homepage hero. One image, or several that crossfade as a carousel. Pick them from your library with the asset picker instead of typing UUIDs.

Standalone Albums

Albums displayed directly on the homepage. + Add Album opens the Album Picker.

Each album supports:

• Title override — a display name instead of the Immich album name
• Description — shown below the album title
• Password — protect a single album (written as an scrypt hash)
• Cover image — override the album cover with any asset
• Photo order — Immich order, newest, oldest, filename, or Manual with a drag & drop editor
• Grid override (experimental) — a different grid layout for this album alone (the panel exposes the layout; columns, gap and aspect ratio can be set in gallery.yaml)
• Cover focal point (experimental) — which part of the cover survives the crop

Subpages

Group albums under custom URL paths (e.g. /japan, /wedding-smith).

• Name — navigation label; the URL slug is derived from it
• Title / Subtitle — page heading and subline
• Password — protect the whole subpage
• Page Layout Style — the layout the photos on this page are shown in (masonry, uniform, showcase, …), or essay mode
• Album Cover Grid — how the album covers are tiled: columns (empty = the site-wide grid setting) and gap in px (empty = the theme's own cover spacing). Hidden in essay mode
• Photo Grid (Albums On This Page) — columns and gap for the photos inside those albums; empty follows Settings › Grid. Separate from the cover grid: one field used to size both until #523
• Enabled — take the page offline without deleting it
• Hidden (experimental) — unlisted: reachable by direct link, absent from the navigation
• Essay — turn the page into a photo essay, with a block editor for the text

A live preview shows the page as visitors will see it.

Sections

Within a subpage, albums can be grouped into named sections, which renders a table of contents with anchor links.

Reordering

Subpages, albums and sections are reordered in place; the order in the panel is the order on the site.

Journal

The Journal Studio — a split-screen editor with the blocks on the left and a live preview of the real page on the right, separated by a divider you can drag with mouse, keyboard or touch.

Blocks are added from a menu (heading, text, quote, facts, photo, photo pair, photo grid, album, map), reordered, and deleted; each carries a type chip so long entries stay scannable. Photos are inserted through the asset picker, which fills in the Immich asset UUID for you. A new entry can start from a template — Wedding, Hiking, Travel, Birthday, Portrait Session, Behind the Scenes, Pets, New Series — chosen in the create dialog; the blocks arrive with placeholder text and empty photo tiles to fill. The frontmatter — cover image, title, subtitle, author, date, draft flag, password — is edited as form fields.

Saving writes plain Markdown to content/journal/<slug>.md, which can equally be edited by hand.

→ Journal & Photo Essays for the file format.

Settings

Eight sections, each at its own URL (/admin/settings/theme, …):

Section	Controls
General	Site title, subtitle, language, favicon upload, and the feature toggles (EXIF on hover, map, transitions, scroll-to-top, analytics)
Theme	Preset, colour mode, accent, photo frame, hero style, grain, header dot
Grid	Layout algorithm, columns, gap, aspect ratio
Footer	Name, Instagram, email, website, and the header navigation links
Legal	Impressum toggle and all legal fields, the contact form and its notification, the privacy policy
SEO	Meta title, subpage title template, description, noindex, nofollow
Security & Protection	Right-click and image-drag deterrents, lightbox watermark (text, position, opacity)
About	Portrait asset, name, location, gear list, and the biography — written to content/about.md

Theme presets, grid layouts, photo frames, hero styles and the Google search snippet are picked from preview cards rather than text fields, so the effect of a choice is visible before saving. A light/dark toggle previews both variants of a preset.

Favicon

General → Favicon accepts an SVG, PNG, ICO or JPEG. It is stored in the writable content/ volume and served through /api/favicon under a policy that stops an uploaded SVG from executing script. Reset restores the bundled default.

Proofing

Private client links: pick a client name and any Immich album — published or not — and optionally an expiry date and download rights. Each card shows the link's state (open, submitted, expired), what the client picked, and the export buttons. See Client Proofing Links for how the client side works.

Analytics

View counts per page and album, read from content/analytics.json. No cookies, no third party, nothing leaving your server. Switch the collection off entirely in Settings → General; the tracking endpoint then refuses to record.

Privacy Policy

Settings → Legal → Privacy Policy edits content/privacy.md, shown at /privacy and linked in the footer once it has text. It is Markdown: ## headings, - lists, **bold** and links.

Folio writes no legal text for you. Next to the editor it lists what this site processes, read off your configuration: where photos and fonts come from, whether the map, visitor statistics, the contact form, password cookies or a CDN are in use, and which of them involve a third party. Insert headings adds the section headings that list implies, and nothing else. Earlier versions are kept under Backups, like the About page.

Diagnostics warns while the Impressum is on and there is no privacy policy.

Messages

The inbox of the contact form at /contact, switched on under Settings → Legal. Each message is a file in content/messages/ and is deleted automatically after the retention period (90 days unless set otherwise). Opening a message marks it read; Reply by email opens your own mail client with the sender's address and the message quoted, since Folio sends no mail itself.

To hear about new messages, set a Notification URL. Folio POSTs a fixed "A new message arrived" to it, with nothing about the sender: no name, no address, no text. So no personal data reaches the push service. That fits ntfy: install the app, subscribe to a topic name nobody can guess, and paste https://ntfy.sh/<topic> (or the URL of your own ntfy server). Any other endpoint that accepts a plain-text POST works too. CONTACT_NOTIFY_URL in the environment overrides the field. Without a notification, the Diagnostics page warns: a contact channel nobody reads does not count as one.

Spam protection works without a captcha: a hidden field only bots fill in, a minimum time between opening the form and sending it, three messages a minute per IP, and a cap of 500 stored messages. At the cap new messages are refused rather than old ones dropped.

Album & Asset Pickers

Album Picker — a modal listing all shared albums from your Immich instance, not just the configured ones:

• Search by album name or UUID
• Photo count per album
• "In use" badge for albums already assigned somewhere
• Sorted configured-first, then alphabetically

Asset Picker — browses your full Immich library for hero images, album covers, journal photos and the about-page portrait. It uses POST /search/metadata, which is covered by the asset.read permission your API key already needs.

Security

Aspect	Implementation
Authentication	HMAC-signed session token in an HttpOnly cookie
Signing key	Derived from AUTH_SECRET with scrypt
Session expiry	24 hours (automatic logout)
Password check	Constant-time comparison to prevent timing attacks
Cookie flags	HttpOnly, Secure (in production), SameSite=Strict
Rate limiting	POST /api/admin/auth is capped at 5 attempts per minute per IP
Authorization	Every /api/admin/* route re-checks the session, including analytics
Robots	/admin is marked noindex, nofollow in metadata

Note

The admin panel uses its own session management, completely separate from album password protection. Rotating AUTH_SECRET invalidates every admin session along with every unlocked gallery.

Backups

Every time you save, the previous file is backed up automatically. Deleting a journal entry keeps a copy too:

content/.backups/
├── gallery.yaml.2026-05-29T14-30-00-000Z.bak
├── settings.yaml.2026-05-29T14-30-00-000Z.bak
├── about.md.2026-05-29T14-30-00-000Z.bak
└── ...
content/journal/.backups/
├── my-story.md.2026-05-29T14-30-00-000Z.bak
└── old-trip.md.2026-05-30T09-12-00-000Z.deleted.bak

• Up to 10 backups per file are retained (oldest are pruned)
• The Backup Manager (dashboard) has a tab each for gallery, settings, about and journal, and restores any backup with a single click — a deleted journal entry comes back under its old slug
• Before a restore, a *.pre-restore.bak snapshot is created
• *.deleted.bak and *.pre-restore.bak snapshots are never pruned
• All writes are atomic (write to temp file, then rename) — no risk of a half-written YAML

Docker Usage

The admin panel works seamlessly with Docker deployments since the content/ directory is typically a volume mount:

services:
  lightbox:
    image: immich-folio
    environment:
      - ADMIN_PASSWORD=your-secure-password
    volumes:
      - ./content:/app/content # Must be writable for admin panel

Important

The content volume must be read-write (not :ro). The admin panel, the journal, the favicon upload, the setup wizard and the backup rotation all write into it.

Reload Button

The admin header includes a ↻ Reload button that:

1. Invalidates the in-memory config cache
2. Clears the Immich album/asset cache
3. Forces the next request to re-read all YAML files

This is useful after making external changes to config files or when Immich data has changed.

Diagnostics

The status badge in the header opens a short summary: whether Immich answers, whether gallery.yaml and settings.yaml parse, the number of cached entries, and the backup count with the timestamp of the most recent one. settings.yaml is optional, so its absence is not a fault — only a file that exists and cannot be parsed counts as invalid. A check that could not run (an expired session, for example) is reported as such rather than as an outage.

The Diagnostics tab in the top bar leads to the full page at /admin/diagnostics. Anything that wants a look is listed first; the checks that passed follow, grouped into connection, security and content. Each finding that wants a look links to where it is fixed — a finding about one album opens the subpage it is published on (or, for a standalone album, the album itself). The page also manages backups and clears the cache, and Copy report puts the findings on the clipboard as Markdown, ready for a GitHub issue.

It also reports alt text. Folio has no alt-text field of its own: the Immich description of a photo becomes its alt text, as long as Photo Description is switched on under Settings → General. The page counts the published photos that have no description and lists them by album, each linking to the photo in Immich. Add the description there and press Reload. The links use Immich's own External domain (Administration → Settings → Server in Immich) when it is set. Otherwise they fall back to the address Folio reaches Immich at, which is often an internal Docker name your browser cannot open. Missing alt text does not colour the status badge — most libraries have some, and a badge that is never green stops being read.

Separately, while you are logged in, the public site shows a diagnostic banner on any album Immich returns empty — the case that otherwise looks like a broken page to you and to nobody else.

The same checks are available from the terminal as npm run doctor, which needs neither a running app nor this password — see Config Doctor. Use it when the site does not come up far enough to reach this panel.