Link Previews (Sharing)¶
| Field | Value |
|---|---|
| Status | Approved |
| Version | 1.0 |
| Last Updated | 2026-07-26 |
| Author | Claude |
| Reviewed By | — |
When someone shares a locali link in a messenger or social network, the service fetches the page and shows a small preview — title, short description, image. This page explains how locali generates these previews, which data becomes visible, and what to keep in mind when operating an instance.
How the previews are generated¶
Preview crawlers (WhatsApp, Signal, Telegram, Mastodon, Facebook …) execute no JavaScript — a plain single-page app would show the same generic preview for every link. That is why the web container injects the OpenGraph tags server-side at the web edge: for known share targets, the serving process asks the public API for the target's metadata and replaces the default tags in the page before it reaches the crawler. If that fails (timeout, unknown target), the untouched page with neutral default tags is served instead — the preview degrades, the app never breaks.
What becomes visible in a preview¶
Only publicly visible data is ever emitted — preview resolution uses the same visibility rules as the public pages themselves:
| Shared link | Preview shows |
|---|---|
| Organisation profile | Name, short description (or an excerpt of the description), logo — published organisations only |
| Organisation news item / event | Title, text excerpt, item image (falling back to the organisation logo) |
| Place (public map) | Name, category and description excerpt, image — published places only |
| Open space | The space's name and short description — never member content |
| Closed space | Deliberately neutral: only the instance's default preview — not even the space name reaches a crawler |
Recipients who open a link into a protected space land on a friendly sign-in page instead of a raw login redirect — after signing in they continue to the original destination.
Configuration (optional)¶
The preview feature works without extra configuration. Two optional environment variables of the web container allow fine-tuning:
| Variable | Purpose | Default |
|---|---|---|
LOCALI_PUBLIC_WEB_URL |
Public web origin used for absolute og:url / image addresses |
The request's Host header (with https) |
LOCALI_SHARE_PREVIEW_API_URL |
Internal API address for preview lookups — useful when the public API address is not reachable from inside the container network | LOCALI_API_BASE_URL |
Login page in the app language (Keycloak)¶
On sign-in and registration the app forwards the current app language as the OIDC parameter
ui_locales. For the Keycloak login page to actually follow that language, the realm must have
internationalization enabled (Realm settings → Localization). If it is disabled, Keycloak
ignores the parameter and shows its default language.
Testing previews — the cache effect¶
Messengers cache previews aggressively
Many services cache a link's preview for a long time — a message that has already been shared does not refresh its preview, even if the underlying data changed long ago. In addition, the web edge itself briefly caches preview responses (around two minutes), including misses. To test a change, paste the link freshly into a new message or wait a moment — or use the respective platform's preview debugging tool.