Quick Start

This guide will get HERITRACE running on your local machine in just a few steps.

Prerequisites

• Docker and Docker Compose installed
• Modern web browser

Quick 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

Create a new directory for HERITRACE:

mkdir heritrace && cd heritrace

Download HERITRACE configuration:

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

Optionally download database management scripts for quick setup:

Linux/MacOS

curl -o start-databases.sh https://raw.githubusercontent.com/opencitations/heritrace/main/start-databases.sh

curl -o stop-databases.sh https://raw.githubusercontent.com/opencitations/heritrace/main/stop-databases.sh

chmod +x start-databases.sh stop-databases.sh

Windows

curl -o Start-Databases.ps1 https://raw.githubusercontent.com/opencitations/heritrace/main/Start-Databases.ps1

curl -o Stop-Databases.ps1 https://raw.githubusercontent.com/opencitations/heritrace/main/Stop-Databases.ps1

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

Option A: Quick start with provided databases

Start databases first:

Linux/MacOS

./start-databases.sh

Windows

.\Start-Databases.ps1

Start HERITRACE:

docker compose up

Option B: Use your existing databases

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

docker compose up

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.

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?

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

When you’re done, stop the services:

Stop Application

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

docker compose down

Stop Databases

Linux/MacOS

./stop-databases.sh

Windows

.\Stop-Databases.ps1

Troubleshooting

Port Already in Use

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

Linux

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

macOS

netstat -an | grep -E ':(5000|8998|8999)\s'

Windows

Check ports using netstat:

netstat -ano | findstr ":5000 :8998 :8999"

Or using PowerShell:

Get-NetTCPConnection | Where-Object {$_.LocalPort -in 5000,8998,8999}

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