Skip to main content

Set up execution information

In this tutorial you start Neo4j with Docker, configure one Apache Hop project to record into it, run a workflow, and look at the run in the Neo4j Browser. Everything runs on one machine.

Before you start​

You need:

  • Docker with Compose v2.20 or later (docker compose version).
  • Apache Hop 2.20 or later, in Putki 2026.12 or later or on its own, and a project with at least one workflow, one run configuration and one environment file.
  • jq, used by the installer to edit the project's files.
  • Ports 7474 (Neo4j Browser) and 7687 (Bolt, where Hop writes) free on this machine.

1. Download the bundle​

Download putki-graph-logging-<version>.zip from the Releases page of your Putki distribution repository on forge.putki.io, unzip it and open a terminal in the folder:

unzip putki-graph-logging-<version>.zip
cd putki-graph-logging-<version>

2. Set the password and start Neo4j​

./init-env.sh             # asks for NEO4J_PASSWORD; Enter makes one up
docker compose -f docker-compose-neo4j.yml up -d
docker compose -f docker-compose-neo4j.yml ps

After half a minute neo4j is healthy. The password is kept in .env, readable only by you: grep NEO4J_PASSWORD .env. For a scripted install, ./init-env.sh --generate asks nothing, and NEO4J_PASSWORD="$FROM_YOUR_VAULT" ./init-env.sh takes yours.

3. Configure your project​

Close Hop GUI first, or reopen the project afterwards. Then:

./install-execution-logging.sh --project-home /path/to/your/project \
  --neo4j-host localhost --neo4j-password 'the NEO4J_PASSWORD from .env'

The installer:

  • adds a graph database connection neo4j, and an execution information location putki-neo4j that uses it, to the project's metadata;
  • points the project's run configurations at that location, unless one already points at another;
  • writes the connection settings, the password among them, and HOP_GRAPH_LOGGING_CONNECTION into every environment file in the project's environments folder.
caution

The environment files now hold the Neo4j password. Keep them out of version control.

If it warns that no run configuration references putki-neo4j, or that no environment file was found, fix that first: without them nothing is recorded.

4. Run a workflow​

In Hop GUI, select the project and one of its environments, and run a workflow with a run configuration of the project. From the command line:

/path/to/hop/hop-run.sh -j <project> -e <environment> -r local -f '${PROJECT_HOME}/main.hwf'

5. Look at the run​

Open http://localhost:7474 and sign in as neo4j with NEO4J_PASSWORD. Run:

MATCH p = (:Execution {executionType: "Workflow"})-[:EXECUTES*1..3]->(:Execution)
RETURN p LIMIT 25

The workflow's run appears with the pipelines and transforms it ran. Click a node to see its status and log.

Next steps​