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 start \
  --port 9000 \
  --frontend-port 9000 \
  --host http://localhost \
  -s ./frontend

After the server starts

http://localhost:9000/web/

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

# Health probe — returns 200 OK with server uptime
http://localhost:9000/health

# Runtime info — name, version, build_time, environment,
# host/ports, access_mode, registration_mode, default_user_role
http://localhost:9000/info

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="3f9c2a..."
curl -s http://localhost:9000/api/v1/dictionary_term \
  -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 (real shipped example) ===

#Identification
name=Robert Vokac
description=Zettelkasten system for Robert Vokac
environment=Development
dev_mode=false
#
#host=
#port=
#frontend_port=
database_type=SQLite

#Access
access_mode=PublicFullAccess
registration_mode=Free
default_user_role=Reader

#Other
max_log_level=ERROR
allowed_plugins=slip_box, repetition, dictionary
access_token_expires_in=15                  # minutes
refresh_token_expires_in=43200              # minutes (= 30 days)
refresh_token_rotation_threshold_in=10080   # minutes (= 7 days)

Configuration keys reference

Configuration can also be edited at runtime by a SuperAdmin via the built-in web form at /api/v1/superadmin/configure — fields requiring a restart (host, ports, database, allowed plugins) are marked, with an optional scheduled restart.

Command-line flags reference (start command)

Command-line flags override the corresponding hive.properties values. Everything else (tokens, access mode, plugins, cache) is configured via the properties file or the SuperAdmin configure UI.

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 — real template shipped in the repository
# (replace the {PLACEHOLDER} values with your paths)
[Unit]
Description=Hive (C++ REST backend)
After=network.target

[Service]
Type=simple
User={USER}
Group={USER}
WorkingDirectory={WORKING DIRECTORY}

ExecStart={PATH}/hive start --port 9000 --frontend-port 443 \
    --host {HOST} -s {PATH TO frontend}
Restart=on-failure
RestartSec=5s

Environment=USER={USER} HOME={HOME}

StandardOutput=append:/var/log/hive.log
StandardError=append:/var/log/hive.err

# kill settings — graceful shutdown
KillSignal=SIGINT
TimeoutStopSec=10

[Install]
WantedBy=multi-user.target

Note the template's --frontend-port 443: when a TLS reverse proxy terminates HTTPS on 443, the frontend must call the API through the proxy port, not Hive's internal port.

# 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/GoogleMock test suite under tests/, built as the Tests target (enabled by default via ENABLE_TESTS=ON) and registered with CTest through gtest_discover_tests().

# Configure with tests (ON by default)
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DENABLE_TESTS=ON
cmake --build build --target Tests

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

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

# Run directly with GoogleTest output
./build/tests/Tests --gtest_filter="AccessMode*"

Test coverage areas (from tests/hive/)

Common Issues