Development setup

This guide explains how to set up HERITRACE for local development from source code.

Prerequisites

• Docker and Docker Compose
• Git
• Modern web browser

Development environment setup

1. Clone the repository

git clone https://github.com/opencitations/heritrace.git && \
cd heritrace

2. Configure environment

Copy the example environment file and edit it with your settings:

cp .env.example .env

The default configuration runs in demo mode (FLASK_ENV=demo), which bypasses ORCID authentication. To enable ORCID login, set FLASK_ENV=development and configure ORCID_CLIENT_ID, ORCID_CLIENT_SECRET, and ORCID_SAFELIST in .env.

3. Start databases

Start the required databases (if not already running):

# Linux/macOS
./dev/start-databases.sh

# Windows
.\dev\Start-Databases.ps1

This will start:

• Virtuoso triplestore for main data (port 8890)
• Virtuoso triplestore for provenance data (port 8891)

4. Start development environment

docker compose -f dev/docker-compose.dev.yaml up --build

The development environment will:

• Build the application with development dependencies
• Mount source code for live editing
• Serve the application with Gunicorn (--reload for automatic restarts on code changes)
• Generate a self-signed SSL certificate on first startup
• Start the application on https://localhost:5000

Development features

Demo mode

Setting FLASK_ENV=demo in .env:

• Bypasses ORCID authentication
• Allows immediate access without ORCID configuration

Hot reload

Gunicorn runs with --reload, so changes to Python files automatically restart the workers. Watched paths include:

• Python source files in heritrace/
• app.py, config.py

Volume mounts

The following directories are mounted for live editing:

• ./heritrace → Application source code
• ./default_components → Default URI generator and counter handler
• SHACL schema and display rules from example_configurations/

Development commands

Application management

# Start development environment
docker compose -f dev/docker-compose.dev.yaml up --build

# Start without rebuilding
docker compose -f dev/docker-compose.dev.yaml up

# View application logs
docker compose -f dev/docker-compose.dev.yaml logs web

# Stop development environment
docker compose -f dev/docker-compose.dev.yaml down

# Restart just the web service
docker compose -f dev/docker-compose.dev.yaml restart web

Database management

# Start databases
./dev/start-databases.sh  # Linux/macOS
.\dev\Start-Databases.ps1  # Windows

# Stop databases
./dev/stop-databases.sh  # Linux/macOS
.\dev\Stop-Databases.ps1  # Windows