Getting started¶

This page takes you from nothing to a running SHMARQL site that queries Wikidata, in a few minutes.

What you need¶

• Python 3.11 or newer and uv, the Python package manager SHMARQL uses — or Docker.

• A copy of the SHMARQL source code:

  git clone https://github.com/epoz/shmarql.git
  cd shmarql
  

You don't need Node.js: the story editor comes pre-built with SHMARQL.

Run it with uv¶

uv sync                 # create .venv and install the dependencies
uv run shmarql          # serve on http://127.0.0.1:8000

Open http://127.0.0.1:8000. You see the documentation that comes with SHMARQL (the docs/ folder of the repository).

Other useful commands:

uv run shmarql serve --reload        # development: restart when the code changes
uv run shmarql --host 0.0.0.0 --port 8080
uv run shmarql profiles              # list the SPARQL profiles and their keys

Connect to Wikidata¶

SHMARQL needs at least one SPARQL endpoint, called a profile. The quickest way to get one is the ENDPOINT setting:

ENDPOINT=https://query.wikidata.org/sparql uv run shmarql

With no profiles file, this creates a single profile for Wikidata and makes it the default. /sparql, the query editor, the entity viewer and data stories all use it.

For anything beyond a quick test, describe the endpoint in a profiles file instead. Then you can give it a name, a timeout, a polite User-Agent and entity-viewer settings. Create profiles.yaml in the folder you start SHMARQL from:

default: wikidata
profiles:
  - name: wikidata
    title: Wikidata
    endpoint: https://query.wikidata.org/sparql
    headers:
      User-Agent: "my-shmarql-site/1.0 (https://example.org/; me@example.org)"
    timeout: 60
    uri_prefixes:
      - http://www.wikidata.org/entity/
    display:
      construct_query: "CONSTRUCT { {subject_uris} ?p ?o . } WHERE { {subject_uris} ?p ?o . }"
      show_inverse_relations: false

SHMARQL reads profiles.yaml by default (change it with PROFILES_PATH). SPARQL profiles explains every line.

Use the example configuration¶

This documentation comes with a complete configuration in its config/ folder:

To serve this documentation, with every example working, start SHMARQL with:

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 \
uv run shmarql

…or copy config/env.example to .env in the SHMARQL folder, fix the paths, and run uv run shmarql. Settings in .env are read at startup; Configuration lists them all.

Run it with Docker¶

The repository contains a Dockerfile, and a ready-made image is published on the GitHub Container Registry as ghcr.io/epoz/shmarql.

docker build -t shmarql .          # or use ghcr.io/epoz/shmarql

docker run --rm -p 8000:8000 \
  -v /path/to/shmarql_docs:/docs:ro \
  -e DOCS_PATH=/docs \
  -e PROFILES_PATH=/docs/config/profiles.yaml \
  -e LODEON_CONFIG_PATH=/docs/config/lodeon.yml \
  shmarql

The container listens on port 8000. Mounting the folder read-only (:ro) is fine for reading. To publish stories from the editor, the docs folder has to be writable (leave out :ro) and LODEON_EDITOR_TOKEN has to be set (see the story editor).

Check that it works¶

Something not working? See Troubleshooting.

Next steps¶

• Learn the query editor and the entity viewer.
• Replace the documentation with your own: writing documentation pages.
• Write your first data story in the story editor.