Configuration

Hedis configuration is managed through environment variables and a MongoDB connection. This guide covers all configuration options for running the decompiler, building the database, and analyzing apps.

Environment Variables

Hedis uses a .env file for configuration, automatically loaded via godotenv/autoload (see pkg/database/main.go:16).

Creating the Configuration File

Create a .env file in go/hermes-decompiler/:

cd go/hermes-decompiler
touch .env

Add your configuration:

# MongoDB Connection
MONGO_CONNECTION_STRING=mongodb://localhost:27017
MONGO_DB_NAME=hedis

# Hermes Compiler Platform
OS_HERMES=osx-bin

# GitHub API Access (optional, for security advisories)
GITHUB_TOKEN=ghp_your_personal_access_token_here

Required Variables

MONGO_CONNECTION_STRING

Purpose: MongoDB connection URI for storing fingerprints and package metadata. Format: Standard MongoDB connection string. Examples:

MONGO_CONNECTION_STRING=mongodb://localhost:27017

Error if missing:

MONGO_CONNECTION_STRING is not set
exit status 1

OS_HERMES

Purpose: Specifies the Hermes compiler binary platform for the pipeline. Values:

osx-bin — macOS (Intel or Apple Silicon)
linux64-bin — Linux x64

Default: osx-bin (if not set) How it’s used (from pkg/cmd/maintainDatabase.go:44):

osHermes := os.Getenv("OS_HERMES")
hermesCompilerPath := filepath.Join(
  reactNativeWorkingDirectory,
  "node_modules/react-native/sdks/hermesc",
  osHermes,  // ← osx-bin or linux64-bin
  "hermesc"
)

When to change:

Running on a Linux server: OS_HERMES=linux64-bin
Running on macOS: OS_HERMES=osx-bin (default)

Optional Variables

MONGO_DB_NAME

Purpose: MongoDB database name for storing Hedis collections. Default: hedis When to customize:

Running multiple environments (dev, staging, prod)
Separating vulnerable package data from general packages

Example:

# Development environment
MONGO_DB_NAME=hedis_dev

# Production
MONGO_DB_NAME=hedis_prod

GITHUB_TOKEN

Purpose: GitHub Personal Access Token for querying the Security Advisory API. Required for: maintain-database -s and maintain-database -g commands. How to create:

Generate a PAT

Go to GitHub → Settings → Developer settings → Personal access tokens → Generate new token (classic)

Select scopes

Required scope:

public_repo (for accessing public security advisories)

Optional:

read:org (if querying private organization advisories)

Add to .env

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Usage example (from pkg/pipeline/security.go):

token := os.Getenv("GITHUB_TOKEN")
headers := map[string]string{
  "Authorization": "Bearer " + token,
}
// Query GitHub GraphQL API for security advisories

MongoDB Setup

Local Installation

macOS
Linux
Docker

brew tap mongodb/brew
brew install [email protected]
brew services start [email protected]

Verify:

mongosh
# MongoDB shell version v2.x.x

# Ubuntu/Debian
wget -qO - https://www.mongodb.org/static/pgp/server-7.0.asc | sudo apt-key add -
echo "deb [ arch=amd64 ] https://repo.mongodb.org/apt/ubuntu $(lsb_release -cs)/mongodb-org/7.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list
sudo apt update
sudo apt install -y mongodb-org
sudo systemctl start mongod

Verify:

sudo systemctl status mongod
mongosh

docker run -d \
  --name mongodb \
  -p 27017:27017 \
  -v mongodb_data:/data/db \
  mongo:7.0

Connection string:

MONGO_CONNECTION_STRING=mongodb://localhost:27017

MongoDB Atlas (Cloud)

For production or remote access:

Create a cluster

Whitelist IP

Database Access → Network Access → Add IP Address → Add Current IP

Create database user

Database Access → Add New Database User

Username: hedis_user
Password: (generate strong password)
Role: Read and write to any database

Get connection string

Databases → Connect → Connect your application

MONGO_CONNECTION_STRING=mongodb+srv://hedis_user:[email protected]/hedis?retryWrites=true&w=majority

Database Collections

Hedis uses these MongoDB collections (from README:23):

Collection	Purpose	Index Recommendations
`packages`	npm package metadata (name, version, author, repository)	`package_unique_id` (unique)
`hashes`	Function fingerprints per package per RN version	`package_id`, `react_native_version`, `hash.structural_hash`
`hashes_ghsa`	Fingerprints for vulnerable packages only	Same as `hashes`
`baselines_v3`	Empty RN app fingerprints (framework functions)	`react_native_version` (unique)

Creating Indexes

Optimize query performance:

// Connect to MongoDB
mongosh mongodb://localhost:27017/hedis

// Create indexes
db.packages.createIndex({ "package_unique_id": 1 }, { unique: true })
db.hashes.createIndex({ "package_id": 1, "react_native_version": 1 })
db.hashes.createIndex({ "hash.structural_hash": 1 })
db.hashes.createIndex({ "hash.content_ir1_hash": 1 })
db.hashes.createIndex({ "hash.content_ir2_hash": 1 })
db.hashes_ghsa.createIndex({ "package_id": 1, "react_native_version": 1 })
db.baselines_v3.createIndex({ "react_native_version": 1 }, { unique: true })

Verifying Configuration

Test MongoDB Connection

mongosh "$MONGO_CONNECTION_STRING"

Expected output:

Current Mongosh Log ID: 65f1234567890abcdef12345
Connecting to: mongodb://localhost:27017/?directConnection=true
Using MongoDB: 7.0.6
Using Mongosh: 2.1.5

Test Hedis Connection

cd go/hermes-decompiler
go run main.go maintain-database -b

Expected output:

Connecting to database...
Database connected
OS_HERMES: osx-bin
Checking for new React Native Versions to create a baseline for...

Troubleshooting

MONGO_CONNECTION_STRING is not set

Cause: Missing .env file or variable not defined.Solution:

Create .env in go/hermes-decompiler/
Add MONGO_CONNECTION_STRING=...
Verify file location: ls -la go/hermes-decompiler/.env

Failed to connect to MongoDB

Cause: MongoDB not running or incorrect connection string.Solutions:

Check MongoDB is running: mongosh mongodb://localhost:27017
Verify connection string format
For Atlas: check IP whitelist and credentials
Check network/firewall: telnet localhost 27017

Error: Hermes compiler not found

Cause: OS_HERMES points to wrong platform.Solution:

# macOS
OS_HERMES=osx-bin

# Linux
OS_HERMES=linux64-bin

Verify compiler exists:

ls pipeline/react-natives/rn075/node_modules/react-native/sdks/hermesc/
# Should show: linux64-bin/ osx-bin/ win64-bin/

GitHub API rate limit exceeded

Cause: Querying GitHub without authentication (60 requests/hour limit).Solution: Add GITHUB_TOKEN to .env (increases limit to 5000 requests/hour):

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Database queries are slow

Cause: Missing indexes on large collections.Solution: Create indexes (see Creating Indexes above) and check query performance:

db.hashes.find({ "hash.structural_hash": "abc123..." }).explain("executionStats")
// Look for "IXSCAN" (index scan) not "COLLSCAN" (collection scan)

Production Configuration

For production deployments:

Security

# Use authentication
MONGO_CONNECTION_STRING=mongodb://user:password@host:27017/?authSource=admin

# Enable TLS
MONGO_CONNECTION_STRING=mongodb://user:password@host:27017/?tls=true&tlsCAFile=/path/to/ca.pem

Performance

# Use connection pooling
MONGO_CONNECTION_STRING=mongodb://host:27017/?maxPoolSize=50&minPoolSize=10

# Set write concern
MONGO_CONNECTION_STRING=mongodb://host:27017/?w=majority&journal=true

High Availability

# Use replica set
MONGO_CONNECTION_STRING=mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=rs0&readPreference=secondaryPreferred

Environment-Specific Configs

Development

# .env.development
MONGO_CONNECTION_STRING=mongodb://localhost:27017
MONGO_DB_NAME=hedis_dev
OS_HERMES=osx-bin

Staging

# .env.staging
MONGO_CONNECTION_STRING=mongodb://staging-db:27017
MONGO_DB_NAME=hedis_staging
OS_HERMES=linux64-bin
GITHUB_TOKEN=ghp_staging_token

Production

# .env.production
MONGO_CONNECTION_STRING=mongodb+srv://user:[email protected]/hedis?retryWrites=true&w=majority
MONGO_DB_NAME=hedis_prod
OS_HERMES=linux64-bin
GITHUB_TOKEN=ghp_prod_token

Get Started

Core Concepts

CLI Commands

Guides

Architecture

Configuration

Environment Variables

Creating the Configuration File

Required Variables

MONGO_CONNECTION_STRING

OS_HERMES

Optional Variables

MONGO_DB_NAME

GITHUB_TOKEN

MongoDB Setup

Local Installation

MongoDB Atlas (Cloud)

Database Collections

Creating Indexes

Verifying Configuration

Test MongoDB Connection

Test Hedis Connection

Troubleshooting

Production Configuration

Security

Performance

High Availability

Environment-Specific Configs

Development

Staging

Production

Next Steps

Build docs developers (and LLMs) love

Get Started

Core Concepts

CLI Commands

Guides

Architecture

​Environment Variables

​Creating the Configuration File

​Required Variables

​MONGO_CONNECTION_STRING

​OS_HERMES

​Optional Variables

​MONGO_DB_NAME

​GITHUB_TOKEN

​MongoDB Setup

​Local Installation

​MongoDB Atlas (Cloud)

​Database Collections

​Creating Indexes

​Verifying Configuration

​Test MongoDB Connection

​Test Hedis Connection

​Troubleshooting

​Production Configuration

​Security

​Performance

​High Availability

​Environment-Specific Configs

​Development

​Staging

​Production

​Next Steps

Build docs developers (and LLMs) love

Environment Variables

Creating the Configuration File

Required Variables

MONGO_CONNECTION_STRING

OS_HERMES

Optional Variables

MONGO_DB_NAME

GITHUB_TOKEN

MongoDB Setup

Local Installation

MongoDB Atlas (Cloud)

Database Collections

Creating Indexes

Verifying Configuration

Test MongoDB Connection

Test Hedis Connection

Troubleshooting

Production Configuration

Security

Performance

High Availability

Environment-Specific Configs

Development

Staging

Production

Next Steps