Link Previews (Sharing)¶
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 a hub.
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 server-side renders the public pages (SSR): the crawler receives the finished page with title, description, image and canonical address — the same data human visitors see. If the render fails, the neutral app shell with 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 hub'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 addresses; its hostname is also allow-listed for server-side rendering | The request's Host header (with https) |
LOCALI_SHARE_PREVIEW_API_URL |
Internal API address for server-side lookups (e.g. the sitemap) — useful when the public API address is not reachable from inside the container network | LOCALI_API_BASE_URL |
LOCALI_ALLOWED_HOSTS |
Additional comma-separated hostnames allowed for server-side rendering | — |
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, 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.