fix(brand-title): runtime substitution so GHCR-image users can override (#521 follow-up)

@Rekoo-PS confirmed the prior #521 fix landed on beta but reported the
preview still shows the default "PicPeak" title — their brand is
"arkan-studio". Root cause: that fix used Vite's build-time
%VITE_DEFAULT_TITLE% substitution. Self-hosters running the pre-built
ghcr.io/the-luap/picpeak/frontend image can't override at build time
without rebuilding, so they were stuck with whatever the upstream
build baked in.

Pivot to runtime substitution: the frontend container now reads
BRAND_TITLE / BRAND_DESCRIPTION env vars on startup and envsubsts
them into index.html. Change the values in .env, restart the frontend
service, done — no rebuild required.

Mechanics:
  - frontend/index.html: tokens are now ${BRAND_TITLE} /
    ${BRAND_DESCRIPTION} (shell expansion syntax, passes through Vite
    unchanged into the built dist).
  - frontend/Dockerfile: install gettext (provides envsubst), snapshot
    /usr/share/nginx/html/index.html → index.html.tpl at build, install
    docker-entrypoint.sh, wire ENTRYPOINT to it. The .tpl is the
    immutable source — every container start re-renders index.html
    from .tpl, so restarts pick up new env values cleanly (no
    accidental "first-boot env stuck forever" trap).
  - frontend/docker-entrypoint.sh: applies defaults if env unset,
    runs envsubst (locked to BRAND_TITLE + BRAND_DESCRIPTION
    explicitly so /assets/*.js template literals aren't touched if
    anyone ever extends substitution to the bundle), execs nginx.
  - frontend/vite.config.ts: drop the htmlTitleDefaults plugin — no
    longer needed since substitution is fully runtime.
  - frontend/.env.example + .env.production.example: drop the
    VITE_DEFAULT_* docs (the vars no longer have effect).
  - docker-compose.yml + docker-compose.production.yml: pass
    BRAND_TITLE / BRAND_DESCRIPTION env into the frontend service
    with sensible defaults so unconfigured installs work unchanged.
  - .env.example: add BRAND_TITLE / BRAND_DESCRIPTION with comment
    pointing at the social-preview use case.

Verified end-to-end against the built image:
  - BRAND_TITLE="Arkan Studio" BRAND_DESCRIPTION="Wedding photographs
    by Arkan Studio" → index.html serves <title>Arkan Studio</title>
    + og:title="Arkan Studio" + og:description correctly substituted.
  - .tpl preserves ${...} tokens so the next restart can re-substitute.
  - Bundle assets unaffected.
  - Defaults applied when env unset → <title>PicPeak</title>.

Docs PR in picpeak-docs describes the two new env vars under
"Social link preview fallback" in the environment-variables reference.

Refs: #521

This commit is contained in:

Paul Nothaft

2026-05-21 10:00:21 +02:00

parent 53139b8cb8

commit efa6b4a205

9 changed files with 102 additions and 59 deletions

									
										.env.example
									
		+10
		
												View File
												
				@@ -68,6 +68,16 @@ [email protected]

				FRONTEND_URL=https://yourdomain.com

				ADMIN_URL=https://yourdomain.com

				# Static HTML title + description used for social link previews when the

				# fetcher doesn't trigger the per-event OG endpoint — most notably the

				# WhatsApp Business API and various 3rd-party preview-service caches

				# (#521). Set these to your brand so link previews aren't generic.

				# Substituted into index.html at frontend-container start, so changes

				# take effect on the next `docker compose up -d frontend` — no rebuild

				# required.

				BRAND_TITLE=PicPeak

				BRAND_DESCRIPTION=Photo gallery shared with PicPeak.

				# API URL for email assets (logos, images in notification emails)

				# This must be the publicly accessible URL where email recipients can load images.

				# If not set, defaults to http://localhost:3001 which will show broken images in emails.