Get Hive Running

What you need

gcc --version
# gcc (GCC) 14.x.x

# Debian/Ubuntu install:
sudo apt install gcc-14 g++-14

# Debian/Ubuntu
sudo apt install libssl-dev

# Fedora/RHEL
sudo dnf install openssl-devel

# Verify
openssl version
pkg-config --modversion openssl

cmake --version  # 3.20+
ninja --version  # any recent

# Debian/Ubuntu
sudo apt install cmake ninja-build

git --version  # any recent version

# Debian/Ubuntu
sudo apt install git

sudo apt install build-essential gcc-14 g++-14 cmake ninja-build \
                 git libssl-dev

Vendored third-party libraries (no separate install needed)

Step-by-step setup

git clone https://github.com/openeggbert/hive.git
cd hive
git submodule update --init --recursive

cmake -S . -B build \
  -G Ninja \
  -DCMAKE_BUILD_TYPE=Debug

cmake -S . -B build \
  -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_CXX_FLAGS="-O3" \
  -DCMAKE_INTERPROCEDURAL_OPTIMIZATION=ON \
  -DCMAKE_UNITY_BUILD=ON

cmake --build build --target hive_app

# Or with explicit parallelism (adjust to your CPU core count)
cmake --build build --target hive_app -- -j8

./build/src/hive-app/hive_app --help

./build/src/hive-app/hive_app start \
  --port 9000 \
  --frontend-port 9000 \
  --host http://localhost \
  -s ./frontend

[INFO] Loading configuration from configuration/hive.properties
[INFO] Plugin loaded: core
[INFO] Plugin loaded: slip_box
[INFO] Plugin loaded: dictionary
[INFO] Plugin loaded: repetition
[INFO] Applying migrations for plugin: core (3 pending)
[INFO] Applying migrations for plugin: slip_box (2 pending)
[INFO] Migration integrity verified: all chain hashes match
[INFO] Registered 42 model endpoints
[INFO] CronScheduler started (4 worker threads)
[INFO] Hive server listening on http://localhost:9000

After the server starts

http://localhost:9000/web/

# Full metadata contract (drives frontend)
http://localhost:9000/api/v1/model_definition

# Health probe
http://localhost:9000/health
# → { "status": "ok", "db": "ok" }

# Runtime info
http://localhost:9000/info
# → { "version": "...", "plugins": [...] }

http://localhost:9000/web/app_slip_box.html
http://localhost:9000/web/app_dictionary.html
http://localhost:9000/web/app_repetition.html

# Login
curl -s -X POST http://localhost:9000/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"YOUR_PW"}' | jq

# Use the returned access_token
TOKEN="eyJhbG..."
curl -s http://localhost:9000/api/v1/note \
  -H "Authorization: Bearer $TOKEN" | jq

Configuration File Reference

Hive reads configuration/hive.properties on startup. Command-line flags override configuration file values. The actual default configuration shipped with the repository:

# === configuration/hive.properties ===

# Server access mode (controls what requests are permitted globally)
# 0=MaintenanceMode  1=AdminFullAccess  2=AdminAndSuperUserFullAccess
# 3=AuthenticatedReadOnly  4=AuthenticatedFullAccess
# 5=PublicReadOnly  6=PublicCreateAndRead  7=PublicCreateReadUpdate
# 8=PublicFullAccess  (DEFAULT — open for development)
access_mode=PublicFullAccess

# Registration mode
# 0=Free  1=RequiresAdminApproval  2=AdminAddsUsers
registration_mode=Free

# Default role assigned to new registrations (UserRole enum)
# 0=Guest  1=Reader  2=Editor  3=Reviewer  4=Admin  5=SuperAdmin
default_user_role=Reader

# Logging level
# Levels: TRACE DEBUG INFO WARN ERROR FATAL
max_log_level=ERROR

# Enabled domain plugins (comma-separated, core is always loaded)
allowed_plugins=slip_box,repetition,dictionary

# Token expiry
access_token_expires_in=15           # minutes (15 = 15 min)
refresh_token_expires_in=43200       # minutes (43200 = 30 days)
refresh_token_rotation_threshold_in=10080  # minutes (10080 = 7 days)

Command-line flags reference

Access mode recommendations by deployment type

Running as a systemd Service

Hive ships with a hive.service systemd unit file for running as a Linux daemon. Edit paths to match your installation before enabling.

# hive.service — example content
[Unit]
Description=Hive Data Server
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=hive
Group=hive
WorkingDirectory=/opt/hive
ExecStart=/opt/hive/hive_app start \
    --port 9000 \
    --frontend-port 9000 \
    --host http://localhost \
    -s /opt/hive/frontend
Restart=on-failure
RestartSec=5s
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

# Install and enable
sudo cp hive.service /etc/systemd/system/
sudo nano /etc/systemd/system/hive.service     # edit paths

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable hive
sudo systemctl start hive

# Status and logs
sudo systemctl status hive
sudo journalctl -u hive -f                     # live log tail
sudo journalctl -u hive --since "1 hour ago"   # last hour

Production security considerations

• Run under a dedicated hive user — no root required.
• Put Nginx or Caddy in front for TLS termination and rate limiting.
• Set access_mode=AuthenticatedFullAccess (or stricter) in hive.properties.
• Set registration_mode=AdminAddsUsers if the server is not intended for public registration.
• Ensure configuration/hive.properties and hive.db are readable only by the hive user.
• Back up hive.db regularly — this SQLite file contains all your data.

Running the Test Suite

Hive ships a GoogleTest-based test suite. Tests cover: utility functions, access mode logic, plugin registry (topological sort, cyclic dependency detection), and the cron scheduler. Integration tests run against a real SQLite in-memory database.

# Build tests (requires -DENABLE_TESTS=ON, or it may be ON by default)
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DENABLE_TESTS=ON
cmake --build build --target hive_tests

# Run all tests
cd build && ctest --output-on-failure

# Run a specific test filter
ctest -R "PluginRegistry" --output-on-failure

# Run directly with GoogleTest output
./build/tests/hive_tests --gtest_filter="CronScheduler*"

Test coverage areas

Common Issues