32. Running a Node

32.1 Hardware Requirements

• CPU: 8 Cores (Modern architecture: AMD Zen 3+ or Intel Sapphire Rapids). High single-thread performance is required for the dPOH generator.
• RAM: 32 GB minimum (64 GB recommended for RPC nodes).
• Disk: 1 TB NVMe SSD. Mechanical HDDs and network-attached storage (EBS) are not supported due to RocksDB IOPS requirements.
• Network: 1 Gbps symmetric bandwidth.

32.2 Software Requirements

Kortana is strictly written in C++23. You must use a modern compiler:

• GCC 13+
• Clang 16+
• MSVC 19.38+ (Windows environments)

32.3 Building from Source

Kortana vendors its dependencies to guarantee reproducible builds without relying on external package managers downloading unverified code during the build process.

# Clone only the essential directories using sparse-checkout
git clone --filter=blob:none --sparse https://gitlab.com/emeka.iwuagwu/kortanablockchain.git
cd kortanablockchain
git sparse-checkout set kortana-node ops

# Build the node from source
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -DKORTANA_BUILD_TESTS=OFF ..
make -j$(nproc)

32.4 Running with Docker

For users who prefer not to build from source directly on their host machine, Kortana provides a multi-stage Dockerfile that cleanly builds the C++ binaries and packages them in a minimal runtime environment.

# Clone only the essential directories using sparse-checkout
git clone --filter=blob:none --sparse https://gitlab.com/emeka.iwuagwu/kortanablockchain.git
cd kortanablockchain
git sparse-checkout set kortana-node ops

# Build the node image locally
docker build -f ops/docker/Dockerfile -t kortana/node:latest .

# Run the node using docker-compose
cd ops/docker
docker-compose up -d

32.5 Pre-built Binaries for Production Fleets

For production clusters with multiple nodes, building from source on every node (e.g., small cloud instances) is inefficient. Instead, Kortana operators utilize the included ops/release.sh utility:

1. Build from source once on a large, high-CPU machine.
2. Run ops/release.sh publish to upload the compiled binaries to secure cloud storage.
3. On production nodes, run ops/release.sh fetch to instantly download the correct, pre-built binary for deployment without recompiling.

32.6 The Binaries

The build process (or Docker image) produces four primary binaries:

• kortanad: The core daemon. Runs the P2P network, consensus, and execution router.
• kortana-validator: An isolated process that holds the BLS consensus keys and signs blocks. It talks to kortanad over a secure local socket.
• kortana-cli: The command-line interface for interacting with the node.
• quorlinc: The Quorlin smart contract compiler.

32.7 Configuration & Data Directory

Node configuration is managed via a config.toml file.

[network]
p2p_port = 30303
max_peers = 50

[rpc]
http_port = 8545
ws_port = 8546

The data directory (~/.kortana/) holds the RocksDB column families, the WAL, and the node's P2P cryptographic identity.

---