Installation & Setup¶

This guide walks you through installing Hera and configuring the required services. There are two paths: a Quick Install using the provided scripts and Docker, or a Manual Installation for full control over each step.

Prerequisites¶

Requirement	Minimum Version	Notes
OS	Ubuntu 22.04 LTS	Verified with this version
Python	3.9+	Tested with 3.9, 3.10, 3.11
Git	2.x	For cloning the repository
pip	21+	For installing Python packages
Docker	20+	Required for quick install only

Quick Install (recommended)¶

The fastest way to get Hera running. Uses Docker for MongoDB and scripts to automate environment setup.

Installation Flow¶

Diagram

Init --> Config["Creates ~/.pyhera/config.json"]
Config --> Verify["Verify: python -c\n'from hera import Project'"]

--> --> Init --> Config["Creates ~/.pyhera/config.json"] Config --> Verify["Verify: python -c\n'from hera import Project'"] --> -->

Steps¶

Clone the repository:

git clone https://github.com/KaplanOpenSource/hera
cd hera

Run the initialization script:
```
source init_with_mongo.sh
```
This single script will interactively:
- Set up Hera environment variables (HERA_REPO_ROOT, PYHERA_DIR, PYTHONPATH)
- Prompt to create a Python virtual environment at ~/.pyhera/environment with all dependencies installed
- Prompt to persist the environment to ~/.bashrc
- Prompt to auto-activate the Hera environment when you cd into the project directory
- Pull and start a MongoDB 5.0 Docker container with preconfigured credentials
- Create the ~/.pyhera/config.json configuration file automatically
After running, everything is ready to use.

Install system dependencies and third-party tools (optional):

make install-deps       # System packages (libcairo, GDAL, etc.)
make install-paraview   # ParaView 5.11.0
make install-freecad    # FreeCad Python3 bindings
make install-openfoam   # OpenFOAM 10
make install-deps-all   # All of the above

Helper Scripts¶

Script	Purpose
`source set_hera_environment.sh`	Set environment variables, create venv, configure `.bashrc` (called automatically by `init_with_mongo.sh`)
`source activate_hera.sh`	Activate the Hera venv and environment in the current shell
`init_with_mongo.sh`	Full initialization: environment setup + MongoDB via Docker
`./serve_docs.sh`	Start local MkDocs preview server (renders diagrams first)
`python render_diagrams.py`	Render Mermaid diagrams to SVG using Docker (incremental)

Managing MongoDB with Make¶

After initial setup, use the Makefile to manage the MongoDB container:

make mongo-up              # Start MongoDB (data at ~/mongo-db-datadir)
make mongo-down            # Stop MongoDB
make mongo-status          # Check container status
make mongo-logs            # Tail container logs
make mongo-clean           # Remove container and delete all data
make mongo-up MONGO_DATA=/path/to/data   # Override data directory

Running Tests¶

make test-setup            # Create test data directory at ~/hera_unittest_data
make test                  # Run all tests (requires MongoDB + test data)

Building Documentation¶

The documentation site can be built and previewed locally. Diagram images are pre-rendered using a Docker-based Mermaid CLI (pulled automatically on first build).

make docs-build            # Full build: render diagrams + build MkDocs site
make docs-serve            # Render diagrams + start local preview at localhost:8000
make docs-deploy           # Render diagrams + deploy to GitHub Pages

Diagram rendering is incremental — only new or changed diagrams are re-rendered (~2s each). Unchanged diagrams are skipped instantly.

make render-diagrams       # Render new/changed diagrams only
make render-diagrams-force # Re-render ALL diagrams from scratch
make docs-clean            # Remove built site/

Run make help to see all available targets.

Manual Installation¶

If you prefer not to use Docker or need more control over each step, follow these instructions.

Installation Flow¶

Diagram

-> EnvVars --> Dirs Dirs --> MongoInstall --> MongoUsers --> MongoConfig MongoConfig --> VerifyImport --> VerifyCLI

-->
-->-> EnvVars --> Dirs
    Dirs --> MongoInstall --> MongoUsers --> MongoConfig
    MongoConfig --> VerifyImport --> VerifyCLI

--> -->

Step 1: System Packages¶

sudo apt install libcairo2-dev pkg-config python3-dev libgirepository1.0-dev libgdal-dev gdal-bin python3-gdal

Step 2: Clone and Install¶

git clone https://github.com/KaplanOpenSource/hera
cd hera

# Create and activate a virtual environment
python3.9 -m venv heraenv
source heraenv/bin/activate

# Install in development mode
pip install -e .

# Install runtime dependencies
pip install -r requirements.txt

Development Mode

Using pip install -e . installs Hera in editable mode, meaning changes to the source code take effect immediately without reinstalling.

If pip install -r requirements.txt fails, reinstall setuptools first:

pip install --upgrade --force-reinstall setuptools
pip install -r requirements.txt

Step 3: Install GDAL Python Binding¶

Use gdalinfo --version to obtain your OS GDAL version, then:

pip install GDAL==`gdal-config --version`

Step 4: Set Up PATH and Environment¶

Add the following to your shell profile (~/.bashrc, ~/.zshrc, etc.):

export PYTHONPATH=$PYTHONPATH:/path/to/hera
export PATH=$PATH:/path/to/hera/hera/bin

Create required directories:

mkdir -p ~/.pyhera/log/

Use the setup script instead

You can also run source set_hera_environment.sh to configure environment variables interactively, even if you're doing the rest manually.

Environment Variables¶

These variables are optional but useful for testing and advanced configurations:

Variable	Required	Default	Description
`HOME`	Yes (OS)	OS default	Location of `~/.pyhera/config.json`
`TEST_HERA`	No	`~/hera_unittest_data`	Root directory for test data
`RESULT_SET`	No	`BASELINE`	Name of the expected-output result set for tests
`PREPARE_EXPECTED_OUTPUT`	No	unset	Set to `1` to generate test baselines
`MPLBACKEND`	No	system default	Set to `Agg` for headless matplotlib (no display)
`GDF_TOL_AREA`	No	`1e-7`	Tolerance for geometry comparison in tests
`HERA_FULL_LOGGING_TESTS`	No	unset	Set to enable full logging during tests

See the Environment Variables Reference for complete details.

Step 5: MongoDB Setup¶

Install MongoDB 6.0 following the official instructions and ensure it runs on port 27017.

Start MongoDB with mongosh and create users:

use admin

db.createUser(
  {
    user: "Admin",
    pwd: "Admin",
    roles: [ { role: "userAdminAnyDatabase", db: "admin" } , "readWriteAnyDatabase"]
  }
)

use admin
db.createUser(
  {
    user: "{username}",
    pwd:  "{password}",
    roles: [ { role: "readWrite", db: "{dbName}" } ]
  }
)

Then create ~/.pyhera/config.json:

{
    "{username}": {
        "dbIP": "{host}",
        "dbName": "{database name}",
        "password": "{password}",
        "username": "{username}"
    }
}

Config File Format¶

Field	Type	Description
`connectionName`	`str` (top-level key)	A name for this connection. Defaults to the OS username if not specified at runtime.
`username`	`str`	MongoDB username
`password`	`str`	MongoDB password
`dbIP`	`str`	MongoDB server address (hostname:port)
`dbName`	`str`	Name of the MongoDB database to use

Multiple Connections

You can define multiple connection entries in the same config file. Each entry is a top-level key. When creating a Project, you can specify which connection to use via connectionName:

from hera import Project
proj = Project(projectName="MY_PROJECT", connectionName="production")

If connectionName is not provided, Hera uses the current OS username as the key.

What Happens on First Run¶

If ~/.pyhera/config.json does not exist when Hera is first imported, the system will:

Automatically create the directory ~/.pyhera/
Generate a template config.json with placeholder values
Raise an IOError with a message asking you to fill in the connection details

Step 6: Verify Installation¶

Python API¶

from hera import Project, toolkitHome

# Create or connect to a project
proj = Project(projectName="MY_PROJECT")
print(f"Project: {proj.projectName}")
print(f"Files directory: {proj.FilesDirectory}")

# List available toolkits
table = toolkitHome.getToolkitTable("MY_PROJECT")
print(table)

CLI Tools¶

# List database connections
hera-project db list

# List projects
hera-project project list

# List available toolkits
hera-toolkit list --project MY_PROJECT

Expected Output¶

If everything is configured correctly, you should see:

No IOError about missing config files
A list of database connections
A list of registered toolkits (may be empty for a new project)

Troubleshooting Installation¶

Problem	Cause	Solution
`IOError: config file doesn't exist`	Missing `~/.pyhera/config.json`	Create the file with valid MongoDB connection details
`ConnectionRefusedError`	MongoDB not running	Start MongoDB: `sudo systemctl start mongod` or `make mongo-up`
`ModuleNotFoundError: No module named 'hera'`	Package not installed	Run `pip install -e .` from the hera root
`command not found: hera-project`	`hera/bin/` not in PATH	Run `source activate_hera.sh` or add to PATH manually
`ImportError: mongoengine`	Missing dependencies	Run `pip install -r requirements.txt`

See the Troubleshooting page for more common errors and solutions.