Koko210/immich-folio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

release: v0.18.0 (#725)

Browse Source 
Release v0.18.0 — merges `dev` into `main`.

## Thanks

- [@lancetm714](https://github.com/lancetm714) for the accent-contrast
fix (#680 → #724).
- [@RichKidsDev](https://github.com/RichKidsDev) for reporting the
outdated Impressum (#697).

### Security

- **Journal drafts and password-protected entries no longer render
publicly
  as a subpage essay**
  ([#684](https://github.com/ralksta/immich-folio/pull/684),

[GHSA-987w-cpwm-c9g9](https://github.com/ralksta/immich-folio/security/advisories/GHSA-987w-cpwm-c9g9),
medium). A subpage's `essayFile` read the journal entry straight from
disk,
skipping the draft and password rules `/journal/<slug>` applies. It now
resolves through the same rules: a draft reads as missing for visitors,
and
  a protected entry shows its password gate, sharing the
  `lb_auth_journal_<slug>` cookie.

- **Immich descriptions are escaped in generated subpage essays**
  ([#684](https://github.com/ralksta/immich-folio/pull/684),

[GHSA-8ppx-39jv-q5xm](https://github.com/ralksta/immich-folio/security/advisories/GHSA-8ppx-39jv-q5xm),
  low). The essay built from a subpage's albums (`layout: essay` without
markdown) put each asset's Immich description into the page as raw HTML.
Captions are now HTML-escaped, and they go through `assetCaption()`, so
  `exif.caption: false` is respected there as well. Tracked in
  [#689](https://github.com/ralksta/immich-folio/issues/689).

- **Admin drafts no longer keep a typed password, and the contact form's
  email check runs in linear time**
([#727](https://github.com/ralksta/immich-folio/pull/727)). The admin's
  session drafts wrote a password as typed to `sessionStorage`; a draft
holding a plaintext password is now not kept (the unsaved-changes guard
still warns). The email pattern could backtrack polynomially on a
crafted
domain; its labels now exclude the dot and the length is checked first.
  Both found by CodeQL before release.

### Added

- **A built-in contact form with an inbox in the admin**
  ([#703](https://github.com/ralksta/immich-folio/pull/703), closes
[#702](https://github.com/ralksta/immich-folio/issues/702)). `/contact`
  needs neither SMTP nor a form service: each message is one file in
`content/messages/` (mode `0600`), read under the new _Messages_ tab,
where
_Reply by email_ opens the owner's mail client with the message quoted.
Messages older than `contact.retentionDays` (default 90) are deleted. An
optional ntfy push goes to `contact.notifyUrl` or `CONTACT_NOTIFY_URL`,
and
since [#709](https://github.com/ralksta/immich-folio/pull/709) it
carries a
  fixed "new message" line and nothing about the sender — no name, no
  address, no text. Spam is kept out without a captcha: an off-screen
honeypot, a minimum fill time, three submissions a minute per IP and a
cap
of 500 stored messages. With the Impressum on and no `legal.contactUrl`,
the Impressum links the form as its second contact channel. A new doctor
  check warns when the form is on but nobody is notified.

- **A privacy policy page, next to a list of what the site processes**
  ([#708](https://github.com/ralksta/immich-folio/pull/708)). `/privacy`
renders `content/privacy.md`, edited under Settings → Legal, and the
footer
links it once the file has text; `privacy.enabled: false` hides it.
Folio
writes no legal text. Beside the editor it lists what _this_
installation
  does, read off the configuration — the map, statistics, contact form,
password cookies, CDN — and marks every entry that involves a third
party.
_Insert headings_ adds the matching section headings and nothing else.
The
  doctor warns while the Impressum is on and there is no policy.

- **French, Spanish, Italian and Dutch interface translations**
([#681](https://github.com/ralksta/immich-folio/pull/681)), selected
with
  `settings.yaml: lang` as before. The admin panel stays English.

- **CDN mode for photos and videos**
([#681](https://github.com/ralksta/immich-folio/pull/681)). With
`CDN_URL`
set, image and video URLs point at a pull CDN whose origin is this
server,
  so repeat views reach neither the server nor Immich. A site password
switches the mode off, since a CDN would hand out cached photos without
  checking the unlock cookie. The CDN origin is added to the CSP, and a
  doctor check covers the password and `TRUSTED_PROXY_HOPS` cases. See
  `docs/deployment.md#cdn-mode`.

- **A reworked admin panel**
  ([#712](https://github.com/ralksta/immich-folio/pull/712),
  [#713](https://github.com/ralksta/immich-folio/pull/713),
  [#714](https://github.com/ralksta/immich-folio/pull/714),
  [#716](https://github.com/ralksta/immich-folio/pull/716),
  [#717](https://github.com/ralksta/immich-folio/pull/717),
  [#718](https://github.com/ralksta/immich-folio/pull/718),
  [#719](https://github.com/ralksta/immich-folio/pull/719),
  [#721](https://github.com/ralksta/immich-folio/pull/721)):
- **A sidebar instead of the header row**, grouped by task, with an
unread
    count on Messages and a dot on Diagnostics while Immich is down. It
    collapses to an icon rail, with names shown on hover and focus, and
    remembers that per browser.
  - **`/admin` is an overview**: what needs attention (unread messages,
    doctor warnings), published pages, journal entries and recent views.
  - **The site's own visual language** — the preset's fonts, hairline
borders, the square marker — and one page header on every screen. The
accent is kept for the current place and the primary action; switches
    are now pills reading ON or OFF, in green rather than the accent, so
    Studio Modern's red no longer makes an enabled setting look like an
    error.
- **The page builder is a structure list and a panel.** Hero, subpages
and
standalone albums sit in one list on the left, subpages drag-sorted in
    place; the selected entry is edited on the right instead of in an
    overlay.
- **Dialogs only where a change is permanent.** Deleting a message or a
journal entry, and resetting the favicon (which used to delete the file
without asking), go through one confirm dialog in the admin's own look.
Removals in the page builder, which only touch unsaved state, happen at
    once and offer _Undo_. No `window.confirm()` is left.
  - **Feature switches are grouped by meaning** as one-line rows under
Settings → General; page transitions and scroll-to-top moved to Theme →
    Look & motion. No setting keys changed.

### Changed

- **Fonts and the Leaflet stylesheet are served from the site itself**
([#700](https://github.com/ralksta/immich-folio/pull/700)). Every page
used
to link `fonts.googleapis.com`, which sends each visitor's IP address to
Google. The server now fetches a theme's Google fonts once, rewrites the
  stylesheet and caches the files in `content/.fonts/`; custom fonts in
`theme.fonts` keep working. If Google cannot be reached before a font is
  cached, the page falls back to the theme's system fonts. `leaflet.css`
  comes from the npm package instead of unpkg. The CSP drops
  `fonts.googleapis.com`, `fonts.gstatic.com` and `unpkg.com`.

- **Email addresses are kept out of the served HTML**
([#705](https://github.com/ralksta/immich-folio/pull/705)). The
Impressum
and footer render the address only after hydration, from an encoded
form,
  so harvesters reading raw HTML find nothing. Without JavaScript the
Impressum shows `name [at] example [dot] de`. This defeats bulk
harvesting,
  not a person with a browser.

- **The Impressum cites § 5 DDG and links its contacts**
  ([#698](https://github.com/ralksta/immich-folio/pull/698), reported in
  [#697](https://github.com/ralksta/immich-folio/issues/697) by
[@RichKidsDev](https://github.com/RichKidsDev)). The TMG was replaced by
the
DDG in May 2024; `legal.heading` replaces the line for other laws (e.g.
  § 5 ECG in Austria). `legal.contactUrl` and `legal.contactLabel` add a
  contact form as the second channel, so a phone number stays optional.
  Email, phone and contact URL are now links, and the "Created with the
Impressum generator by eRecht24" line, shown on every site whether true
or
not, is gone. Settings → Legal gains fields for heading, contact URL,
VAT
  ID and tax number, and a doctor check flags missing details.

- **Missing pages answer `404`**
([#704](https://github.com/ralksta/immich-folio/pull/704)). Every
missing
  page used to answer `200`, because streaming had started before
`notFound()` ran. `/contact`, `/impressum`, `/map` and `/privacy` while
switched off, and `/journal/<slug>` without an entry, now return a real
404 with the same not-found page. Album and subpage slugs still depend
on
  Immich and stay soft 404s.

- **Passwords set in the admin are stored as scrypt hashes**
  ([#706](https://github.com/ralksta/immich-folio/pull/706), closes
  [#690](https://github.com/ralksta/immich-folio/issues/690)). Subpage,
album, journal-entry and site passwords were written as typed. The save
routes now hash them; a stored hash reads _Protected_ with _Change_ and
_Remove_ and is never put into an input. Visitors who unlocked a page
stay
signed in across unrelated saves. Existing plaintext passwords are
hashed
  the next time their file is saved in the admin.

- **One notification surface in the admin**
([#707](https://github.com/ralksta/immich-folio/pull/707)) replaces
every
`alert()`: errors stay until dismissed, successes clear themselves, and
  screen readers announce both.

### Fixed

- **Map tiles load again**
([#701](https://github.com/ralksta/immich-folio/pull/701)). CARTO
started
answering every tile with an "API KEY REQUIRED" image, leaving `/map`
and
journal map blocks as a grey grid. Tiles now come from OpenStreetMap;
the
  dark look is a CSS filter, so the map now follows the colour mode.

- **The page builder no longer drops a subpage's `proofing:` flag on
save**
([#711](https://github.com/ralksta/immich-folio/pull/711)). A page
switched
  off for proofing by hand reverted after any unrelated edit.

- **Unsaved edits in Settings and About survive switching admin tabs,
and a
  backup restore is no longer overwritten by the next save**
([#687](https://github.com/ralksta/immich-folio/pull/687)). Editors that
were open during a restore now reload and offer unsaved edits back as a
  conflict. Also: "Restore my changes" after a conflict found nothing,
removing an album left its drawer showing the next album, and the
journal
  saved (rotating a backup) without changes.

- **Accent-backed buttons stay readable with a light or malformed
accent**
  ([#724](https://github.com/ralksta/immich-folio/pull/724), supersedes
[#680](https://github.com/ralksta/immich-folio/pull/680)) — contributed
by
  [@lancetm714](https://github.com/lancetm714). A white accent made the
  proofing dialog's _Download selected (.zip)_ button white on white.
`theme.accent` is now accepted as hex only and normalised to `#rrggbb`,
anything else falls back to the preset, and the proofing dialog and
filter
  pills use the mode-aware `--on-accent` text colour from #688.

- **Every preset's accent is visible in both colour modes**
([#688](https://github.com/ralksta/immich-folio/pull/688)). Presets had
one
accent for both modes; minimal's dark mode drew black buttons on black.
  Presets now carry a light and a dark accent, and text on accent-filled
  buttons picks black or white for contrast. A custom accent stays the
  owner's choice in both modes.

- **Visitor-side inconsistencies**
([#685](https://github.com/ralksta/immich-folio/pull/685)): after
visiting
`/impressum`, every subpage header turned centred and uppercase; back
links
  announced "Back to Back to …"; the hero EXIF chip ignored
`exif.location`/`camera`/`settings`; videos in journal entries opened as
  stills; the setup screen named a non-existent `.env.example`.

- **An essay's lightbox walks only the photos the story shows**
([#686](https://github.com/ralksta/immich-folio/pull/686)), not every
photo
of the subpage's albums, and the proofing bar in essays shows the
selection
  count instead of a filter button that did nothing.

- **The page panel scrolls with the mouse wheel**
  ([#720](https://github.com/ralksta/immich-folio/pull/720)).

- **The journal editor's top bar wraps on phones**
  ([#723](https://github.com/ralksta/immich-folio/pull/723), closes
[#675](https://github.com/ralksta/immich-folio/issues/675)), so the
title
  stays editable and Save stays on screen.

- **Every admin form field has a name for assistive technology**
([#715](https://github.com/ralksta/immich-folio/pull/715)). Only two
inputs
had a linked label; 47 are linked now, and clicking a label focuses its
  field.

### Internal

- **`SettingsEditor` and `PageBuilder` are split up**
  ([#710](https://github.com/ralksta/immich-folio/pull/710),
[#711](https://github.com/ralksta/immich-folio/pull/711)). The
2,200-line
settings editor is a shell with one file per section; the page builder's
YAML handling and edits are pure functions under test. Both were checked
  side by side against `dev` for identical output.
- **`useAdminFetch()`**
([#707](https://github.com/ralksta/immich-folio/pull/707))
gives Analytics, Messages, Backups and the journal list one loading and
  error pattern.
- README brought up to v0.17.0
  ([#678](https://github.com/ralksta/immich-folio/pull/678),
  [#679](https://github.com/ralksta/immich-folio/pull/679)).

### Upgrade notes

**`content/` gains two directories the app writes to:**
`content/.fonts/`
for the cached fonts and `content/messages/` for contact-form messages.
Both
are created on demand, so a writable `content/` is enough, as before.

**The server needs outbound HTTPS to Google once per font** to fill the
font
cache. Until then pages fall back to the theme's system fonts. Visitors'
browsers no longer contact Google.

**A custom CSP or reverse-proxy allowlist** must now allow
`tile.openstreetmap.org` for images instead of
`*.basemaps.cartocdn.com`,
and no longer needs `fonts.googleapis.com`, `fonts.gstatic.com` or
`unpkg.com`. The built-in CSP is updated.

**`theme.accent` must be hex** (`#rgb`, `#rrggbb` or `#rrggbbaa`).
Anything
else, including a value without `#`, falls back to the preset's accent.

**Plaintext passwords in `gallery.yaml`, `settings.yaml` or journal
entries**
are hashed the next time that file is saved in the admin; one save
clears the
doctor's warning.

**New, optional settings:** `contact.*` (the form is off by default),
`privacy.enabled`, `legal.heading`, `legal.contactUrl`,
`legal.contactLabel`,
and the `CDN_URL` and `CONTACT_NOTIFY_URL` environment variables. See
`content/settings.yaml.example` and `.env.local.example`. In the example
file,
`vatId` and `taxId` had swapped sample values; check yours if you copied
them.

No `IMAGE_CACHE_VERSION` bump is needed this time.

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: ralksta <ralksta@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Ralf <rohlenbo79@gmail.com>
Co-authored-by: Paul Thies <110185070+ImScheinox@users.noreply.github.com>
Co-authored-by: lancetm714 <108419425+lancetm714@users.noreply.github.com>
Co-authored-by: Lance Martin <lancetaylor95@gmail.com>
This commit is contained in:
Ralksta
2026-09-27 14:43:38 +02:00
committed by GitHub
parent eab3b9c257
commit 3193c500e4
155 changed files with 13188 additions and 3539 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
docs/admin-panel.md
View File

@@ -45,8 +45,13 @@ Each area has its own URL, so a section can be bookmarked and the browser's back
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
@@ -111,7 +116,7 @@ Eight sections, each at its own URL (`/admin/settings/theme`, …):
| **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 |
| **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` |
@@ -126,6 +131,22 @@ Theme presets, grid layouts, photo frames, hero styles and the Google search sni
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:

69
docs/admin-ux-concept.md Normal file
View File

@@ -0,0 +1,69 @@
# Admin UX concept
A proposal for reworking the admin panel so it reads as calmly as the portfolio it edits. This document is the plan; the pull request that adds it implements the first stage (shell, overview, visual language) so there is something to look at.
## What is wrong today
Seen on a real install (Studio Modern preset):
- **The header is doing too much.** Seven tabs, a status pill and four buttons share one row. Navigation, global actions and system state compete, and nothing says which of them matters.
- **Red means everything.** The admin inherits the preset accent, and every switched-on card gets a thick accent border. On Studio Modern a settings page is a wall of red frames, so the colour no longer marks the one thing that needs attention.
- **There is no starting point.** `/admin` redirects to the page builder. Unread messages, a failing Immich connection or a missing privacy policy are only found by visiting the right tab.
- **Pages do not share a layout.** Settings has a sidebar, Analytics a centred column, Diagnostics its own grid. Titles, descriptions and actions sit in a different place on each.
- **It does not look like the site.** The portfolio has a clear typographic voice: Archivo for text, IBM Plex Mono in uppercase for labels, square red markers, hairline rules. The admin uses a generic system font and rounded cards.
## Principles
1. **The photographs are the loudest thing.** The chrome is monochrome. Colour is reserved for state.
2. **One accent, few uses.** The preset accent marks exactly three things: the current place (the nav marker), the primary action on a screen, and switches that are on. Everything else is grey. Warnings stay amber and errors red, independent of the preset (as `--admin-warning` already does).
3. **The same frame everywhere.** Every screen has a page header (kicker, title, one sentence, actions on the right) and content below it at one maximum width.
4. **Say what needs attention before it is asked for.** The overview surfaces unread messages, health and gaps; the nav carries counts.
5. **Borrow the site's voice.** Headings and body in the site's own fonts, labels in its caption font, uppercase and letter-spaced, as on the public pages.
## Information architecture
A left sidebar replaces the tab row, grouped by what the owner is doing:
| Group | Entries |
| -------- | ----------------------------------- |
| — | **Overview** (new) |
| Content | Pages · Journal |
| Visitors | Messages (unread count) · Analytics |
| Site | Settings |
| System | Diagnostics (health dot) · Help |
Global actions move out of the header into the sidebar foot: _View site_, _Backups_, _Reload_, _Sign out_, plus the version. The header row disappears; each screen's own header takes its place.
### Overview (`/admin`)
The first screen after signing in. Everything on it is a link to where it is acted on:
- **Needs attention**: unread messages, a doctor warning or error, a missing privacy policy. Empty when there is nothing, with a single calm line saying so.
- **At a glance**: pages published, journal entries (drafts), photos on the home page hero, views in the last 7 days.
- **Quick actions**: new journal entry, edit pages, open the site.
## Visual language
| Token | Today | Proposed |
| ------- | --------------------------------------- | --------------------------------------------------------------------------------------- |
| Surface | #111 / #1a1a1a cards with 12px radius | #0c0c0c canvas, #141414 panels, 4px radius |
| Borders | 1px #2e2e2e, 2px accent on active cards | 1px hairline everywhere; active cards keep the hairline, their switch carries the state |
| Type | system UI font | the site's `--font-sans`; labels in `--font-caption`, uppercase, 0.12em tracking |
| Accent | on borders, icons, headings, switches | nav marker, primary button, on-switches |
| Density | 36px controls, mixed spacing | 36px controls, an 8px spacing scale |
Light mode follows the same rules with inverted surfaces.
## Stages
1. **Shell, overview, visual language** (this PR): sidebar with groups and counts, `/admin` overview, tokens and typography, calmer cards. No screen's behaviour changes.
2. **Page headers**: one `PageHeader` component on every screen; remove the per-screen title variants.
3. **Forms**: one field, switch and dialog pattern (#694); replaces `confirm()` with an inline confirmation.
4. **Page builder** (done): the structure (hero, subpages, standalone albums) as an always-visible list on the left, the selected entry edited in a panel on the right instead of an overlay, with Edit / Live preview in the panel header. Builds on the split in #608.
5. **Mobile**: the sidebar collapses into a sheet; not a priority for how the panel is used today, but the grid should not break.
## Not changing
- The admin stays English (see `docs/gallery-config.md`).
- Folio stays a read-only Immich client; nothing in this plan writes to Immich.
- The live preview in the page builder stays; it is how the owner checks changes.

64
docs/deployment.md
View File

@@ -17,6 +17,7 @@ For the quick path — clone, `npm run dev`, open `/install` — see the
- [Config Doctor](#config-doctor)
- [Behaviour when Immich is Unreachable](#behaviour-when-immich-is-unreachable)
- [Reverse Proxy](#reverse-proxy)
- [CDN Mode](#cdn-mode)
## What the Setup Wizard Writes
@@ -43,7 +44,8 @@ server, so a typo cannot leave you with an "installed" site that loads no photos
`IMMICH_API_URL`, `IMMICH_API_KEY`, `AUTH_SECRET` and `ADMIN_PASSWORD` override
anything in `install.json`, so any of them can be rotated by setting the variable
— no need to touch the file. `SITE_PASSWORD` works the same way over
`sitePassword` in `settings.yaml`.
`sitePassword` in `settings.yaml`, and so does `CONTACT_NOTIFY_URL` over
`contact.notifyUrl`.
Set all of them up front and the wizard never appears, which is the usual choice
for an infrastructure-as-code deployment.
@@ -112,7 +114,9 @@ Checks an installation from the terminal and prints what it finds: whether
`settings.yaml` parse, whether Immich answers the three calls Folio depends on,
whether every published album ID still exists in Immich (and is shared there),
whether any password is still stored in plaintext or as an unusable bcrypt
hash, and whether `content/` can be written to.
hash, whether an enabled Impressum has a name, address, email and a second
contact channel, whether the contact form notifies anyone, and whether
`content/` can be written to.
This is the same set of checks as the **Diagnostics** page in `/admin`, but it
needs neither a running app nor an admin password — which is the point. It is
@@ -200,3 +204,59 @@ and Traefik send it on their own; nginx needs the
Opening the app over plain HTTP, e.g. `http://server:7211` on a home network,
works too: the cookies are then set without `Secure`, since a browser would
discard them otherwise.
## CDN Mode
With `CDN_URL` set, every photo and video URL on the site points at a pull CDN
instead of this server:
```env
CDN_URL=https://cdn.example.com
```
```
https://cdn.example.com/api/image/v2:…?size=preview&w=1080&q=75
```
The CDN uses Immich Folio as its origin. The first request for a photo is a
cache miss and goes to `/api/image` as usual; every request after that is
answered by the CDN and never reaches your server or the Immich box behind it.
On a home connection with a slow uplink, that is the difference between a
gallery that crawls and one that does not.
**Setting up the CDN.** Create a pull zone (Bunny), a distribution
(CloudFront) or a CNAME'd subdomain (Cloudflare) whose origin is your public
Folio URL, then:
- **Cache `/api/image/*` and `/api/video/*`**, and nothing else. Pages are
rendered per request, and other routes check cookies.
- **Include the full query string in the cache key.** `size`, `w`, `q` and the
`IMAGE_CACHE_VERSION` buster `v` all select a different file.
- **Respect the origin's `Cache-Control`.** Photos come back
`public, max-age=31536000, immutable`; errors (429, 503, 404) come back
`no-store` and must not be cached.
- **Forward `Range` requests** for videos, so seeking works.
**Rate limiting.** A cache miss arrives from a CDN edge, not from the visitor.
Set `TRUSTED_PROXY_HOPS` to count the CDN as a proxy (Cloudflare → Caddy = 2)
so the limiter reads the visitor's IP from `X-Forwarded-For`; otherwise a
handful of edges share one bucket. The [Config Doctor](#config-doctor) warns
when CDN mode is on with `TRUSTED_PROXY_HOPS=0`.
**What stays on this server:** pages, `/_next` assets, EXIF, the map,
downloads, the admin panel and the Open Graph images. These are either small or
carry a cookie check a CDN would bypass.
**Site passwords switch it off.** On a password-protected site, the image
route checks the visitor's unlock cookie, and a CDN would answer from its cache
without asking. So while a site password is set, photos stay on this server
whatever `CDN_URL` says, and the diagnostics page says so. Gallery (per-page)
passwords are unaffected: they already protect the page that holds the photo
links, not the image URLs themselves.
**Changing a photo.** A CDN keeps immutable responses for as long as a browser
does. Bump `IMAGE_CACHE_VERSION` after regenerating thumbnails in Immich, which
changes every URL at once, or purge the CDN.
The Content-Security-Policy allows the CDN's origin for `img-src` and
`media-src` automatically.

51
docs/gallery-config.md
View File

@@ -285,8 +285,10 @@ Three storage formats are accepted:
To get the hash for an existing plaintext password, unlock the gallery once and
read the server log: the successful unlock prints the matching `scrypt:…` line
to paste back into `gallery.yaml`. The admin panel writes the hashed form
directly.
to paste back into `gallery.yaml`. Simpler: open the page or album in the
admin panel and save it once. Every password saved there is stored as a
`scrypt:…` hash, and the field then reads **Protected** with **Change** and
**Remove** instead of showing the stored value.
> [!NOTE]
> Album and subpage gates protect the **page**. Image URLs handed out while a
@@ -533,18 +535,26 @@ lightbox, the password gate, the proofing dialog, the legal notice, error pages
| ----- | ----------------- |
| `en` | English (default) |
| `de` | German |
| `fr` | French |
| `es` | Spanish |
| `it` | Italian |
| `nl` | Dutch |
Any other value (`fr`, `ja`, …) still reaches `<html lang>` and
Region subtags are accepted and dropped for the interface (`fr-CA` → French,
`nl-BE` → Dutch), while the full value still reaches `<html lang>`.
Any other value (`ja`, `pt`, …) still reaches `<html lang>` and
`toLocaleDateString`, but the interface stays English: there is no dictionary
for it yet. That is deliberate — claiming `lang="en"` on a French site would be
worse for screen readers than an English interface on a page correctly marked
as French.
as Japanese.
Two things stay in one language by design:
- **The admin panel** is always English, whatever `lang` says.
- **`/impressum`** keeps its German headings when `lang: de` and the § 5 TMG
citation in both, because that is what the statute names. Under `lang: en`
- **`/impressum`** keeps its German headings when `lang: de` and the § 5 DDG
citation in every language, because that is what the statute names
(`legal.heading` replaces it where another law applies). Under `lang: en`
the footer link reads "Legal Notice" rather than "Impressum" — the page is
optional (`legal.enabled`), and an unexplained German word in the footer of
an English site is what drove this out of the backlog.
@@ -553,7 +563,12 @@ Adding a language means adding one file under `lib/i18n/locales/` and listing
it in `SUPPORTED_LOCALES` (`lib/i18n/index.ts`). The dictionary is typed
against the English one, so a missing key fails the type-check rather than
falling back silently, and `lib/__tests__/i18n.test.ts` additionally catches
keys that were copied over but never translated.
keys that were copied over but never translated. Words a language genuinely
shares with English (`ISO`, `Info`, French "photos") go into that locale's
allowance list in the same test, which in turn fails if an entry stops being
identical. Add the language to the **Language** select in
`app/admin/components/SettingsEditor.tsx` so it can be picked from the admin
panel.
### Analytics
@@ -678,6 +693,28 @@ footer:
A `legal:` block with `enabled: true` adds an Impressum page at `/impressum` and
links it in the footer — see `content/settings.yaml.example` for every field.
Email, phone and `contactUrl` render as links. `contactUrl` is a second contact
channel such as a contact form, which case law accepts in place of a phone
number; it takes http(s) URLs only and is dropped with a warning otherwise.
`heading` replaces the "Angaben gemäß § 5 DDG" line, e.g. for § 5 ECG in Austria.
A privacy policy is written in the admin panel and stored in
`content/privacy.md`; `/privacy` shows it and the footer links it once the file
has text. `privacy: { enabled: false }` hides it without deleting the file. See
[Privacy Policy](admin-panel.md#privacy-policy).
A `contact:` block with `enabled: true` adds a contact form at `/contact` and
links it in the footer. Messages stay on the server (`content/messages/`) and
are read in the admin panel; see [Messages](admin-panel.md#messages). While the
Impressum has no `contactUrl`, it links this form as the second contact channel.
```yaml
contact:
enabled: true
notifyUrl: https://ntfy.sh/your-secret-topic # optional push for new messages
retentionDays: 90 # delete messages after this many days
```
## About Page
Create `content/about.md` with YAML frontmatter:

7
docs/journal.md
View File

@@ -260,9 +260,10 @@ A `password` in the frontmatter puts the entry behind the same gate used for
subpages and albums. The unlock cookie is `lb_auth_journal_<slug>` and expires
after 24 hours.
Store a hash rather than the plaintext where possible — the `scrypt:salt:hash`
format described in [Gallery Configuration](gallery-config.md) applies here too.
A plaintext password works but is logged as a warning at startup.
A password set in Journal Studio is stored as a `scrypt:salt:hash`, never as
typed. For hand-written frontmatter the same format described in
[Gallery Configuration](gallery-config.md) applies. A plaintext password works
but is logged as a warning.
## Journal Studio

6
docs/theming.md
View File

@@ -111,12 +111,16 @@ The brand color used for hover effects, navigation highlights, the header dot, a
### `fonts`
Google Fonts names. Fonts are loaded automatically — just use the name as it appears on [fonts.google.com](https://fonts.google.com). Three font slots:
Google Fonts names, as they appear on [fonts.google.com](https://fonts.google.com). Three font slots:
- **heading** — album titles, hero title, section labels
- **body** — navigation, descriptions, UI text
- **caption** — EXIF metadata, photo captions
Visitors never contact Google. The server fetches the stylesheet and the font files on first use, keeps them in `content/.fonts/` and serves them from your own domain through `/api/fonts`. Loading Google Fonts straight from Google sends every visitor's IP address there without consent, which a German court ruled unlawful in 2022.
The server therefore needs outbound HTTPS to `fonts.googleapis.com` and `fonts.gstatic.com` the first time a font is used. Once cached, the fonts keep working without it. If Google cannot be reached before that, the page falls back to the system fonts until it can.
### `radius`
Border radius in pixels applied to photo grid items and album cards: