Configuration Guide¶

HiveMatrix uses a centralized configuration system managed by Helm. This guide explains how to configure the platform and all 8 services.

Configuration Architecture¶

Configuration Files¶

hivematrix-helm/
├── apps_registry.json           # Source of truth - service definitions
├── master_config.json           # System-wide configuration
├── services.json                # Auto-generated service list
├── master_services.json         # Auto-generated with master config
└── instance/configs/            # Per-service configs (auto-generated)
    ├── core.conf
    ├── codex.conf
    ├── ledger.conf
    └── ...

Important: Only edit apps_registry.json and master_config.json. The other files are auto-generated.

Configuration Hierarchy¶

apps_registry.json - Defines which services exist and their dependencies
master_config.json - System-wide settings (hostname, databases, keys)
Service configs - Generated by combining registry + master config

Master Configuration¶

Edit instance/configs/master_config.json:

{
  "system": {
    "environment": "production",
    "log_level": "INFO",
    "secret_key": "your-secret-key-here",
    "hostname": "your-domain.com"
  },
  "databases": {
    "postgresql": {
      "host": "localhost",
      "port": 5432,
      "admin_user": "postgres"
    },
    "neo4j": {
      "uri": "bolt://localhost:7687",
      "user": "neo4j",
      "password": "your-neo4j-password"
    },
    "redis": {
      "host": "localhost",
      "port": 6379,
      "db": 0
    }
  },
  "keycloak": {
    "client_secret": "your-keycloak-secret"
  },
  "anthropic": {
    "api_key": "your-anthropic-api-key"
  }
}

System Settings¶

Setting	Description	Default
`environment`	Deployment environment	`production`
`log_level`	Logging verbosity	`INFO`
`secret_key`	Flask secret key (generate with `python -c 'import secrets; print(secrets.token_hex())'`)	Auto-generated
`hostname`	Public hostname or IP	`localhost`

Database Settings¶

PostgreSQL¶

Setting	Description	Default
`host`	PostgreSQL server	`localhost`
`port`	PostgreSQL port	`5432`
`admin_user`	Admin username	`postgres`

Neo4j (KnowledgeTree)¶

Setting	Description	Default
`uri`	Neo4j connection string	`bolt://localhost:7687`
`user`	Neo4j username	`neo4j`
`password`	Neo4j password	Set during install

Redis (Core Sessions)¶

Setting	Description	Default
`host`	Redis server hostname	`localhost`
`port`	Redis port	`6379`
`db`	Redis database number	`0`

Service Registry¶

Edit apps_registry.json to define available services:

{
  "core_apps": {
    "core": {
      "name": "HiveMatrix Core",
      "description": "Authentication & service registry",
      "git_url": "https://github.com/skelhammer/hivematrix-core",
      "port": 5000,
      "required": true,
      "dependencies": ["postgresql"],
      "install_order": 1
    }
  },
  "default_apps": {
    "codex": {
      "name": "HiveMatrix Codex",
      "description": "Central data hub",
      "git_url": "https://github.com/skelhammer/hivematrix-codex",
      "port": 5010,
      "required": false,
      "dependencies": ["postgresql", "core"]
    }
  }
}

Service Definition Fields¶

Field	Description	Required
`name`	Display name	Yes
`description`	Service description	Yes
`git_url`	GitHub repository URL	Yes
`port`	Service port number	Yes
`required`	Must be installed	Yes
`dependencies`	List of dependencies	Yes
`install_order`	Installation sequence	Optional

Syncing Configuration¶

After editing configuration files, sync changes to all services:

cd hivematrix-helm
source pyenv/bin/activate

# Update service configs from registry
python install_manager.py update-config

# Sync master config to all services
python config_manager.py sync-all

# Restart services to apply changes
./stop.sh
./start.sh

Configuration Sync Process¶

update-config reads apps_registry.json and generates services.json and master_services.json
sync-all copies master config and services list to each service's instance/ directory
Services read their config files on startup

Service-Specific Configuration¶

All 8 services have configuration files in instance/configs/. Most are auto-generated by config_manager.py, but some have service-specific settings:

Core Configuration¶

instance/configs/core.conf:

[database]
connection_string = postgresql://core_user:password@localhost:5432/core_db

[redis]
host = localhost
port = 6379
db = 0

[session]
expiration_hours = 1

Codex Configuration¶

instance/configs/codex.conf:

[database]
connection_string = postgresql://codex_user:password@localhost:5432/codex_db

[psa]
default_provider = freshservice
enabled_providers = freshservice

[freshservice]
domain = your-domain.freshservice.com
api_key = your-api-key

[datto]
api_key = your-datto-key
api_secret = your-datto-secret
api_url = https://your-instance.centrastage.net

Ledger Configuration¶

instance/configs/ledger.conf:

[database]
connection_string = postgresql://ledger_user:password@localhost:5432/ledger_db

[billing]
default_tax_rate = 0.0
invoice_prefix = INV-

[archive]
# Archive functionality is integrated (no separate service)
retention_years = 7
auto_snapshot_enabled = true

KnowledgeTree Configuration¶

instance/configs/knowledgetree.conf:

[database]
neo4j_uri = bolt://localhost:7687
neo4j_user = neo4j
neo4j_password = your-password
connection_string = postgresql://knowledgetree_user:password@localhost:5432/knowledgetree_db

[services]
codex_url = http://localhost:5010
core_url = http://localhost:5000

Brainhair Configuration¶

instance/configs/brainhair.conf:

[database]
connection_string = postgresql://brainhair_user:password@localhost:5432/brainhair_db

[anthropic]
api_key = your-anthropic-api-key

[claude_code]
# Official Anthropic Claude Code CLI configuration
allowed_tools = Bash,Read,Grep,Glob,WebFetch,WebSearch
cli_path = /usr/local/bin/claude

[services]
codex_url = http://localhost:5010
ledger_url = http://localhost:5030
knowledgetree_url = http://localhost:5020
core_url = http://localhost:5000

[security]
filter_pii = true
filter_phi = true
filter_cjis = true
require_approval = true

[presidio]
# PHI/CJIS filtering configuration
entities = PERSON,EMAIL_ADDRESS,PHONE_NUMBER,US_SSN,CREDIT_CARD,MEDICAL_LICENSE
anonymize_names = true

Helm Configuration¶

instance/configs/helm.conf:

[database]
connection_string = postgresql://helm_user:password@localhost:5432/helm_db

[logging]
centralized_enabled = true
retention_days = 90
log_directory = logs/

[monitoring]
health_check_interval = 60

Beacon Configuration¶

instance/configs/beacon.conf:

[services]
codex_url = http://localhost:5010

[dashboard]
auto_refresh_seconds = 60
tickets_per_page = 50

Environment Variables¶

Services also support environment variables for sensitive data:

# Set in shell before starting
export ANTHROPIC_API_KEY="your-key"
export FRESHSERVICE_API_KEY="your-key"

# Or create .env file (not recommended for production)
echo "ANTHROPIC_API_KEY=your-key" > .env

Port Configuration¶

Services use fixed ports defined in apps_registry.json. To change ports:

Edit the port number in apps_registry.json
Run python install_manager.py update-config
Restart services

Port Assignments (8 Services + Keycloak):

Service	Port	Protocol	Database
Nexus	443	HTTPS	None (stateless)
Core	5000	HTTP	Redis + PostgreSQL
Beacon	5001	HTTP	None (stateless)
Helm	5004	HTTP	PostgreSQL
Codex	5010	HTTP	PostgreSQL
KnowledgeTree	5020	HTTP	Neo4j + PostgreSQL
Ledger	5030	HTTP	PostgreSQL
Brainhair	5050	HTTP	PostgreSQL
Keycloak	8080	HTTP	Built-in H2

Note: Archive was merged into Ledger and is no longer a separate service.

SSL/TLS Configuration¶

Development (Self-Signed Certificate)¶

Helm generates a self-signed certificate automatically:

hivematrix-nexus/instance/ssl/
├── cert.pem     # Certificate
└── key.pem      # Private key

Production (Let's Encrypt)¶

For production, use Let's Encrypt:

# Install certbot
sudo apt install certbot

# Get certificate
sudo certbot certonly --standalone -d your-domain.com

# Update Nexus config
cd hivematrix-nexus
# Edit app.py to use /etc/letsencrypt/live/your-domain.com/

# Restart Nexus
cd ../hivematrix-helm
./stop.sh && ./start.sh

Keycloak Configuration¶

Keycloak settings are in master_config.json:

{
  "keycloak": {
    "client_secret": "YHl9bhq2TpUuiKPF8O273W587TfiYwdJ"
  }
}

The client secret is generated during initial setup. To regenerate:

Log in to Keycloak admin console (http://localhost:8080)
Go to Clients > hivematrix
Go to Credentials tab
Regenerate secret
Update master_config.json with new secret
Restart services

Logging Configuration¶

Log Levels¶

Set in master_config.json:

{
  "system": {
    "log_level": "DEBUG"  // DEBUG, INFO, WARNING, ERROR, CRITICAL
  }
}

Log Locations¶

hivematrix-helm/logs/
├── core.stdout.log
├── core.stderr.log
├── codex.stdout.log
├── codex.stderr.log
├── keycloak.stdout.log
└── ...

Centralized Logging¶

Services send logs to Helm's database:

# View logs via CLI
cd hivematrix-helm
source pyenv/bin/activate
python logs_cli.py --service core --tail 100

# Or via Helm web UI
# http://localhost:5004/logs

Backup Configuration¶

Configure automated backups:

# Edit crontab
sudo crontab -e

# Add daily backup at 2 AM
0 2 * * * cd /path/to/hivematrix-helm && /usr/bin/python3 backup.py >> /var/log/hivematrix-backup.log 2>&1

See Backup & Restore for details.

Firewall Configuration¶

Generate and apply firewall rules:

cd hivematrix-helm
source pyenv/bin/activate

# Generate rules
python security_audit.py --generate-firewall

# Review
cat secure_firewall.sh

# Apply
sudo bash secure_firewall.sh

This configures ufw to: - Allow SSH (port 22) - Allow HTTPS (port 443) - Block all other external access - Allow localhost connections

Performance Tuning¶

Database Optimization¶

PostgreSQL¶

Edit /etc/postgresql/*/main/postgresql.conf:

shared_buffers = 256MB          # 25% of RAM
effective_cache_size = 1GB      # 50-75% of RAM
work_mem = 16MB
maintenance_work_mem = 128MB
max_connections = 100

Restart PostgreSQL:

sudo systemctl restart postgresql

Neo4j¶

Edit /etc/neo4j/neo4j.conf:

dbms.memory.heap.initial_size=512m
dbms.memory.heap.max_size=2g
dbms.memory.pagecache.size=512m

Restart Neo4j:

sudo systemctl restart neo4j

Service Resources¶

Adjust Python worker processes in each service's run.py:

if __name__ == "__main__":
    app.run(
        host="127.0.0.1",
        port=5010,
        debug=DEBUG,
        threaded=True,  # Enable threading
        processes=1     # Increase for more workers
    )

Troubleshooting Configuration¶

Config Not Applied¶

If changes aren't taking effect:

# Regenerate all configs
cd hivematrix-helm
source pyenv/bin/activate
python install_manager.py update-config
python config_manager.py sync-all

# Restart services
./stop.sh
./start.sh

Service Can't Connect to Database¶

Check database config:

# Test PostgreSQL connection
psql -U postgres -h localhost -p 5432 -l

# Test Neo4j connection
cypher-shell -u neo4j -p your-password -d system

Port Conflicts¶

If a port is already in use:

# Find what's using the port
sudo lsof -i :5000

# Kill the process or change HiveMatrix port in apps_registry.json

Permission Errors¶

Fix file permissions:

cd ~/hivematrix
sudo chown -R $USER:$USER .
chmod -R u+rw .

Next Steps¶

Review Services Overview to understand each service
Check Security Guide for production hardening
See Development Guide for creating custom services