Skip to content

Homer Configuration Wizard

The homer wizard subcommand generates a complete homer.json configuration file. It supports both an interactive TUI mode and non-interactive preset profiles.

Quick Start

# Interactive wizard (step-by-step TUI)
homer wizard

# Non-interactive: generate config for a deployment profile
homer wizard --profile all-in-one
homer wizard --profile all-in-one --output /etc/homer/homer.json

Flags

Flag Description Default
--output <path> Output file path homer.json
--profile <name> Non-interactive preset (skips TUI) -

Deployment Profiles

Profiles pre-configure which modules are enabled:

Profile Ingest Storage Node Coordinator Use Case
all-in-one yes yes yes yes Single-server deployment
writer yes yes no no Ingest + storage only (no API)
edge yes yes yes no Edge node (ingest + serve data)
coordinator no no no yes API gateway querying remote nodes
node no no yes no Read-only data server

Profile Examples

# All-in-one: everything on one server
homer wizard --profile all-in-one --output homer.json

# Writer: receives HEP and stores to DuckLake, no API
homer wizard --profile writer --output homer-writer.json

# Edge: receives HEP, stores, and serves via FlightSQL
homer wizard --profile edge --output homer-edge.json

# Coordinator: API-only, queries remote nodes
homer wizard --profile coordinator --output homer-coordinator.json

# Node: read-only FlightSQL server
homer wizard --profile node --output homer-node.json

Interactive TUI Mode

Run homer wizard without --profile to enter the interactive wizard:

homer wizard
homer wizard --output /etc/homer/homer.json

Wizard Steps

The wizard walks through 7 steps:

Step 1 -- Deployment Profile

Choose a profile to pre-fill module settings. Selecting all-in-one enables all modules; selecting writer disables node and coordinator, etc. You can change individual settings in subsequent steps.

Step 2 -- Ingest Module (skipped if disabled)

  • UDP port (default: 9060)
  • TCP enable/disable
  • HTTP port (default: 9080)
  • Worker count and queue size

Step 3 -- Storage Module (skipped if disabled)

  • DuckLake catalog — sqlite
  • Catalog path (default: /data/homer/homer_catalog.sqlite)
  • Data path for parquet files (default: /data/homer/parquet)
  • Retention days (default: 30, 0 = unlimited)
  • Batch size

Step 4 -- Node Module (skipped if disabled)

  • FlightSQL port (default: 50051)
  • Auth token (optional)

Step 5 -- Coordinator Module (skipped if disabled)

  • API HTTP port (default: 8080)
  • Node host and port to query (default: 127.0.0.1:50051)
  • JWT secret (auto-generated in TUI if empty; always stored in config when using wizard)
  • Admin username and password (empty password → auto-generated; stored as bcrypt in config)
  • Settings DB path

Step 6 -- System Settings

  • Log level: debug, info, warn, error
  • Prometheus metrics: enable + port

Step 7 -- Review & Save

Preview the generated JSON config and choose the output file path. Press Enter to save.

TUI Controls

Key Action
Tab / Down Next field
Shift+Tab / Up Previous field
Enter Next step (or save on review step)
Esc Previous step (or quit on first step)
Ctrl+C Quit without saving

Generated Config Structure

The wizard generates a complete homer.json with all modules configured:

{
  "ingest": {
    "enable": true,
    "worker_count": 8,
    "queue_size": 80000,
    "udp": { "enable": true, "host": "0.0.0.0", "port": 9060 },
    "http": { "enable": true, "host": "0.0.0.0", "port": 9080 },
    "hep": { "hepv2_enable": true, "hepv3_enable": true, "protobuf_enable": true }
  },
  "storage": {
    "enable": true,
    "ducklake": {
      "catalog_type": "sqlite",
      "catalog_path": "/data/homer/homer_catalog.sqlite",
      "data_path": "/data/homer/parquet",
      "lake_name": "homer_lake",
      "batch_size": 10000,
      "flush_interval_sec": 30,
      "compaction": { "enable": true, "check_interval_sec": 1800, "retention_days": 30 }
    }
  },
  "node": {
    "enable": true,
    "flight_server": { "enable": true, "host": "0.0.0.0", "port": 50051 },
    "ducklake": { "catalog_path": "/data/homer/homer_catalog.sqlite", "data_path": "/data/homer/parquet" }
  },
  "coordinator": {
    "enable": true,
    "http_server": { "enable": true, "host": "0.0.0.0", "port": 8080 },
    "nodes": [{ "name": "local", "host": "127.0.0.1", "port": 50051 }],
    "jwt": { "secret": "<auto-generated>", "expire_hours": 24 },
    "auth": { "type": "internal" }
  },
  "log": { "level": "info", "output": ["stdout"] },
  "prometheus": { "enable": true, "host": "0.0.0.0", "port": 9090 }
}

Disabled modules have "enable": false but retain their default settings, so they can be enabled later by editing the config.

Security Notes

  • Admin bootstrap uses "coordinator.auth": {"type":"internal"} in the generated file. If you leave Admin Password empty in the TUI, the wizard generates a random password, stores its bcrypt hash in JSON, and displays the cleartext once after save. If you enter a password, that value is bcrypt-hashed in the config. Passwords are never written in plaintext in JSON.
  • On coordinator startup without wizard (empty admin_password_hash), a random bootstrap password is logged once — see SECURITY.md.
  • JWT secret in the TUI: if left empty, a random value is generated and embedded in the saved homer.json. Coordinator startup with empty JWT in a hand-edited config instead persists /.homer_jwt_secret beside the settings DB.
  • The generated config file is written with 0644 permissions. Restrict access if it contains sensitive tokens.

Post-Generation

After generating a config, you can run Homer immediately:

# Generate config
homer wizard --profile all-in-one --output /etc/homer/homer.json

# Install DuckDB extensions (first time only)
homer system --install-extensions

# Start Homer
homer --config-path /etc/homer/homer.json

Or edit the generated file to fine-tune advanced settings like TLS, S3 storage, storage policies, remote logging (Loki/Elasticsearch), and OAuth2 providers.