Configuration¶

SHMARQL is configured with environment variables. When it starts, it first reads a .env file in the current folder, if there is one. Use SHMARQL_ENV_FILE to read another file. Real environment variables win over the file.

A .env for the examples in this documentation (see config/env.example):

SITE_TITLE=SHMARQL × Wikidata
DOCS_PATH=/path/to/shmarql_docs
PROFILES_PATH=/path/to/shmarql_docs/config/profiles.yaml
LODEON_CONFIG_PATH=/path/to/shmarql_docs/config/lodeon.yml
SPARQL_TIMEOUT=60
LODEON_EDITOR_TOKEN=change-me-to-a-long-random-string

The SPARQL endpoints themselves live in a separate YAML file: see SPARQL profiles.

The site¶

Variable	Default	Meaning
`SITE_TITLE`	`SHMARQL`	Shown in the header and in page titles.
`HOST`	`127.0.0.1`	Address to listen on. Use `0.0.0.0` to accept connections from other machines.
`PORT`	`8000`	Port to listen on.
`DEBUG`	`0`	`1` for verbose logging.
`DOCS_PATH`	`docs`	Folder with the Markdown pages (see writing documentation pages).
`DEFAULT_LANGUAGE`	`en`	Fallback language for the interface and for labels, when the browser asks for none of the supported ones.
`SUPPORTED_LANGUAGES`	`en,nl`	Interface languages, chosen from the browser's `Accept-Language` header.

SPARQL¶

Variable	Default	Meaning
`PROFILES_PATH`	`profiles.yaml`	The YAML file with the SPARQL profiles.
`ENDPOINT`	–	An endpoint address, such as `https://query.wikidata.org/sparql`. It makes the profile with that address the default (served at `/sparql`). With no profiles configured, it creates a profile for it.
`SPARQL_TIMEOUT`	`30`	Seconds to wait for an upstream endpoint. A profile's `timeout` overrides it.
`SPARQL_USER_AGENT`	`shmarql/0.1 (+https://github.com/epoz/shmarql)`	User-Agent sent upstream when a profile sets none.
`CORS_ORIGINS`	–	Other websites allowed to call the SPARQL endpoint and API from the browser, comma-separated, or `*` for all.

Data stories and the story editor¶

Variable	Default	Meaning
`LODEON_CONFIG_PATH`	–	A YAML file that overrides LODEON's renderer settings, for example which sites may be embedded. See below.
`LODEON_ASSETS_PATH`	–	A folder that replaces the bundled LODEON browser files (scripts, styles). Rarely needed.
`LODEON_EDITOR_ENABLED`	`1`	`0` turns the story editor at `/lodeon/` off.
`LODEON_EDITOR_TOKEN`	–	The password authors use to log in to the editor. Publishing needs it. Without it, everyone can use the editor and Preview, and nobody can publish.
`LODEON_EDITOR_SESSION_TTL`	`28800`	How long an editor login lasts, in seconds (8 hours).
`LODEON_STORY_DIR`	`story`	Folder in `DOCS_PATH` that published stories go to: `DOCS_PATH/story/<slug>/`.
`LODEON_PREVIEW_PATH`	a temporary folder	Where previews are kept.
`LODEON_PREVIEW_TTL`	`3600`	Seconds after which a preview is deleted.
`LODEON_MAX_UPLOAD_MB`	`100`	Largest Preview/Publish upload (story plus media), in MB.

LODEON settings¶

The file named by LODEON_CONFIG_PATH overrides parts of the bundled LODEON configuration. You only list what you change. The example file config/lodeon.yml allows embedding the Wikidata Query Service:

nodes:
  embed:
    allowedOrigins:
      - https://query.wikidata.org
    sandbox: [allow-scripts, allow-same-origin, allow-popups]
    allow: [fullscreen]

Useful settings, all under nodes::

Setting	Default	Meaning
`embed.allowedOrigins`	`[]`	Sites whose pages may be shown in embed nodes. Empty means none.
`embed.sandbox`	`[]`	`sandbox` permissions of embed frames. Empty means fully sandboxed: no scripts.
`embed.allow`	`[]`	`allow` (feature policy) of embed frames, for example `fullscreen`.
`iiif.originPolicy`	allow all HTTPS	Which IIIF servers may be used: `mode: allowAllHttps`, or an allow/block list.
`iiif.defaultHeight`	`520`	Height of IIIF viewers, in pixels.
`leaflet.tileLayers`	OpenStreetMap	Map backgrounds (`urlTemplate`, `attribution`, zoom levels).
`leaflet.defaultCenter`, `defaultZoom`	`[50, 10]`, `5`	Starting view for maps with a fixed view.
`plotly.defaults`	colour-blind-safe palette	Colours, fonts and margins of new Plotly charts.
`<node>.enabled`	`true`	Set to `false` to remove a kind of Special Node from the editor, e.g. `verovio.enabled: false`.

The full list, with defaults, is in the SHMARQL repository at src/shmarql/lodeon/resources/config.yml.