Skip to content

admin-panel.md

Latest commit

 

History

History
208 lines (143 loc) · 11.4 KB

admin-panel.md

File metadata and controls

208 lines (143 loc) · 11.4 KB
Raw

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

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
Analytics /admin/analytics nothing — read-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.

Pages

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, photo, photo pair), 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. 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
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.

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.

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:

content/.backups/
├── gallery.yaml.2026-05-29T14-30-00-000Z.bak
├── settings.yaml.2026-05-29T14-30-00-000Z.bak
└── ...
content/journal/.backups/
└── my-story.md.2026-05-29T14-30-00-000Z.bak
  • Up to 10 backups per file are retained (oldest are pruned)
  • The Backup Manager lists them and restores any one with a single click
  • Before a restore, a *.pre-restore.bak snapshot is created
  • 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 panel reports the health of the installation: 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.

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.