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](#enabling-the-admin-panel)
- [Layout](#layout)
- [Pages](#pages)
- [Journal](#journal)
- [Settings](#settings)
- [Analytics](#analytics)
- [Album & Asset Pickers](#album--asset-pickers)
- [Security](#security)
- [Backups](#backups)
- [Docker Usage](#docker-usage)

## Enabling the Admin Panel

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

```env
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](../README.md#first-run-setup) 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                         |
| **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](admin-ux-concept.md) 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](#album--asset-pickers) instead of typing UUIDs.

### Standalone Albums

Albums displayed directly on the homepage. **+ Add Album** opens the [Album Picker](#album--asset-pickers).

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](https://github.com/ralksta/immich-folio/issues/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](journal.md)** 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.

## 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](https://ntfy.sh): 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:

```yaml
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](deployment.md#config-doctor). Use it when the site does not
come up far enough to reach this panel.