luzzle/docs/web/config.md

Configuration

Start with config.example.yaml. Omitted settings use defaults; unknown settings and invalid values fail validation.

Point the example's $schema comment at your site's /schema.json for the editor schema matching its release. The repository copy is also available for offline use.

Files, URLs, and paths

Edit config/config.yaml. The container's /app/config.yaml alias makes relative paths resolve from /app, not /app/config:

Setting	Default	Purpose
storage.root	./archive	Markdown archive
paths.database	./data/luzzle.sqlite	SQLite index
paths.assets	./assets/pieces	Generated assets
paths.static	./static	Legacy OG font lookup
paths.cache	./nginx	Shared proxy cache

Web and worker need matching mounts. Set url.app to your public URL; it defaults to ${LUZZLE_APP_URL:-http://localhost:8080}. Asset URLs default to same-origin; url.app_assets and url.luzzle_assets accept CDN prefixes. Framework JS/CSS stay same-origin. Use Compose service names for internal addresses.

Restart web and worker after config changes; no rebuild is needed. Republish after piece template or font changes.

Sign-in

Omit auth to disable admin access. Otherwise configure a secret of at least 32 characters and exactly one provider. The example includes password sign-in; generate its secret with openssl rand -hex 32.

For OIDC:

auth:
  secret: "${LUZZLE_AUTH_SECRET}"
  oidc:
    issuer: "${OIDC_ISSUER}"
    clientId: "${OIDC_CLIENT_ID}"
    clientSecret: "${OIDC_CLIENT_SECRET}"

Register /api/auth/callback/oidc on your public origin. Use HTTPS in production. Sessions last seven days; changing the secret invalidates them.

Environment values

Compose loads .env. Reference variables explicitly in YAML:

• ${VAR} requires a value.
• ${VAR:-fallback} uses the fallback when unset, not when empty.
• $$ escapes $; $${VAR} stays literal.

Expansion happens once in string values; catalog names must be literals. Keep .env private. After editing it or changing mounts, run docker compose up -d --force-recreate.

Piece types

Each pieces entry maps an archive type's frontmatter into web fields. title and date_consumed are required. media and attachments take selector lists. title: title reads metadata, not literal text. See archives and templates.

Text and optional features

• Site identity: content.text.title and .description.
• Markdown sections: pages.home.body and pages.feed.about; create files first. Home defaults to latest on, random off; feed links default on.
• Theme tokens: theme.light, .dark, and .globals; quote hex colors. theme.markdown.code.light and .dark default to github-light and github-dark.
• AI: omit ai to disable, or set provider: google and api_key.
• Sync: see remote sync. Keep assets.salt stable to preserve published asset URLs.

Site images

Set content.images.favicon or .opengraph to local filenames, such as ./content/images/share.png. Defaults /images/favicon.png and /images/opengraph.png select bundled images, not filesystem paths.

Files must be nonempty, readable, regular files ≤5 MiB. Favicon accepts PNG/SVG/ICO; OG accepts PNG/JPEG/WebP/GIF. Paths resolve from the supplied config filename. Use the existing content mount; never overwrite build/client files.

Custom images use /assets/favicon/{filename} and /assets/opengraph/{filename}, without the CDN prefix. Unavailable files return 404, not a bundled fallback. Files are reread on use. Piece-specific OG images still take precedence.

Local sans font

content:
  fonts:
    sans: ./content/fonts/my-font.woff2
theme:
  globals:
    font-sans-name: '"My Font"'
    font-sans-weight: "300 900"

Use a licensed WOFF2 file ≤5 MiB; match its family and weights. Paths follow the same rules as images. Browser and worker use this file; the browser URL is /assets/fonts/{filename}, with revalidation. Files are reread on use. Unavailable files return 404; the worker uses renderer fallback fonts. This overrides font-sans-url; omit it to keep existing defaults.

{filename} is the URL-encoded basename, never directories. Browsers revalidate same-name changes. Filename config changes need a restart; old URLs return 404. Purge cached page HTML after config/filename changes.

Error pages

Set pages.error."404", ."4xx", or ."500" independently. Each accepts a config-relative Markdown body and home (default true) for the recovery link. 404 takes precedence over 4xx. Omitted or unreadable bodies use built-in copy; HTTP status codes are preserved. Restart web after changes.