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

• Docker and Docker Compose installed
• Modern web browser

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 the compose file

Create a new directory for HERITRACE and download the configuration:

mkdir heritrace && cd heritrace && \
curl -o docker-compose.yml https://raw.githubusercontent.com/opencitations/heritrace/main/docker-compose.yml

2. Launch

docker compose up

The compose file includes two Virtuoso databases and the web application. Once the databases pass their health checks, the application starts automatically.

HERITRACE runs in demo mode by default (FLASK_ENV=demo) for immediate testing without authentication setup.

To use your own databases instead, edit docker-compose.yml: remove the dataset-db, provenance-db, and networks blocks, remove depends_on and networks from the web service, then set DATASET_DB_URL and PROVENANCE_DB_URL to your database endpoints.

Access the application

Open your browser and navigate to:

http://127.0.0.1:5000

Demo vs Production Mode

Demo Mode: Runs on HTTP with authentication bypassed for immediate testing. Production Mode: Requires HTTPS, valid SSL certificates, and ORCID authentication setup - see Application Settings for configuration details.

Configuration

HERITRACE requires two configuration files:

• SHACL schema (.ttl): Defines the data model, classes, and properties. See SHACL configuration.
• Display rules (.yaml): Controls how entities appear in the interface. See Display rules configuration.
• Custom components (default_components/): URI generator and counter handler implementations. See Application settings.

The example_configurations/ directory contains examples to use as a starting point, including one based on the OpenCitations Data Model (OCDM).

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

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

docker compose down

Troubleshooting

Port already in use

If you get a port conflict on 5000, check what is using it:

Linux

ss -tulpn | grep ':5000\s'

macOS

netstat -an | grep ':5000\s'

Windows

Get-NetTCPConnection | Where-Object {$_.LocalPort -eq 5000}

Need help?

• Review configuration options for advanced setup
• Use docker compose logs to check application logs for specific errors
• Visit the GitHub repository for issues and support