Skip to content
HERITRACE logo HERITRACE

HERITRACE

HERITRACE is a web-based semantic data editor. It lets users enrich and edit RDF metadata through a web interface, without requiring knowledge of the Semantic Web. It handles provenance and change tracking, validates data against SHACL schemas, and connects to existing triplestores with no data transformation needed.

Prerequisites

Section titled “Prerequisites”

Setup

Section titled “Setup”

This method uses official Docker images published to Docker Hub and GitHub Container Registry. All configuration is done through environment variables in the docker-compose.yml file.

1. Download configuration files

Section titled “1. Download configuration files”

Create a new directory for HERITRACE:

Terminal window
mkdir heritrace && cd heritrace

Download HERITRACE configuration:

Terminal window
curl -o docker-compose.yml https://raw.githubusercontent.com/opencitations/heritrace/main/docker-compose.yml

Optionally download database management scripts for quick setup:

Terminal window
curl -o start-databases.sh https://raw.githubusercontent.com/opencitations/heritrace/main/start-databases.sh
Terminal window
curl -o stop-databases.sh https://raw.githubusercontent.com/opencitations/heritrace/main/stop-databases.sh
Terminal window
chmod +x start-databases.sh stop-databases.sh

2. Demo mode (no configuration required)

Section titled “2. Demo mode (no configuration required)”

Demo Mode: HERITRACE runs in demo mode by default (FLASK_ENV=demo) for immediate testing without authentication setup. No configuration changes are required to get started!

Optional Configuration: Edit docker-compose.yml to customize:

  • Database endpoints: Update DATASET_DB_URL and PROVENANCE_DB_URL if using your own databases

3. Launch options

Section titled “3. Launch options”

Option A: Quick start with provided databases

Start databases first:

Terminal window
./start-databases.sh

Start HERITRACE:

Terminal window
docker compose up

Option B: Use your existing databases

Edit docker-compose.yml with your database URLs, then start HERITRACE:

Terminal window
docker compose up

Access the application

Section titled “Access the application”

Open your browser and navigate to:

http://127.0.0.1:5000

Pre-configured data model

Section titled “Pre-configured data model”

HERITRACE comes preloaded with validation and display rules based on a customized version of the OpenCitations Data Model (OCDM):

  • SHACL schema (./shacl.ttl): Defines the data model, classes, and properties.
  • YAML display rules (./display_rules.yaml): Configure how entities appear in the interface
  • Default components (default_components/): Contains the default URI generator and counter handler implementations

What’s next?

Section titled “What’s next?”

Now that HERITRACE is running, you can:

  1. Explore the interface: Navigate through the metadata management features with the preconfigured data model
  2. Production setup: Configure ORCID authentication and security settings for production use
  3. Configure schemas: Customize the SHACL schema for your data model
  4. Set display rules: Modify the YAML display rules for your interface

Stopping the application

Section titled “Stopping the application”

When you’re done, stop the services:

Press Ctrl+C in the terminal running docker compose, or run:

Terminal window
docker compose down

Troubleshooting

Section titled “Troubleshooting”

Port already in use

Section titled “Port already in use”

If you get port conflicts, check if other services are running on the required ports:

Terminal window
# Modern Linux (ss command - usually preinstalled)
ss -tulpn | grep -E ':(5000|8998|8999)\s'

Need help?

Section titled “Need help?”