32. Running a Node

Operating a Kortana full node contributes directly to network decentralization, provides private RPC access for applications, and serves as the foundation for validator participation.

32.1 Hardware Requirements

Running a production kortanad full node or validator requires dedicated server hardware engineered for sustained high-throughput cryptographic and disk I/O performance:

Processor (CPU): Minimum 8 high-frequency cores (3.5 GHz+ base clock, AMD Zen 3/Zen 4 or Intel Sapphire Rapids). Dedicated CPU threads are required for continuous dPOH SHA-256 VDF generation and parallel signature verification.
Memory (RAM): 32 GB DDR4/DDR5 ECC RAM (64 GB strongly recommended for public RPC gateways to support large mempool buffers and state caches).
Storage (Disk): 1 TB NVMe SSD (PCIe 4.0, minimum 5,000 sustained random write IOPS). High-speed NVMe storage is essential for RocksDB state trie flushes and WAL commits.
Network Bandwidth: 1 Gbps symmetric unmetered internet connection with static IPv4 and IPv6 addresses.

32.2 Software Requirements

The Kortana node software is built using the latest C++23 standards and requires a modern Linux operating environment:

Operating System: Linux (Ubuntu 22.04 LTS or 24.04 LTS x86_64 / arm64 recommended).
Compiler: Modern C++23 compiler: GCC 13+ or Clang 17+.
Build Tools: CMake 3.28+, Make or Ninja build systems.
System Libraries: OpenSSL 3.0+, Libsodium, Zstd, and Snappy compression libraries.

32.3 Building from Source

To compile the kortanad daemon and associated utilities directly from source, clone the official repository using Git sparse-checkout and execute the CMake build pipeline:

# Clone the repository using sparse-checkout to minimize download size
git clone --filter=blob:none --sparse https://gitlab.com/emeka.iwuagwu/kortanablockchain.git
cd kortanablockchain
git sparse-checkout set kortana-node ops

# Create build directory and configure Release build
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -DKORTANA_BUILD_TESTS=OFF ..

# Compile all node binaries across all available CPU cores
make -j$(nproc)

The compiled binaries (kortanad, kortana-validator, kortana-cli, quorlinc) will be located in the build/bin/ directory.

32.4 Running with Docker

For containerized production fleets, Kortana provides multi-stage Docker configurations and Docker Compose manifests in the ops/docker/ directory:

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

# Launch the node daemon with persistent volume mounting
docker-compose -f ops/docker/docker-compose.yml up -d

The Docker container runs the kortanad daemon under a dedicated unprivileged system user, mounts local NVMe storage to /var/lib/kortana/data, and exposes standard P2P and RPC ports.

32.5 Pre-built Binaries for Production Fleets

Enterprise node operators managing large validator fleets can utilize the automated packaging script ops/release.sh to generate statically linked binary bundles.

The script compiles the codebase with link-time optimization (-flto), strips debug symbols, generates SHA-256 checksums, and outputs tarballs ready for distribution via Ansible, Kubernetes, or custom orchestration pipelines.

32.6 The Binaries

The Kortana software suite consists of four specialized binary executables:

kortanad: The core blockchain daemon process managing P2P networking, the mempool, dPOH sequencing, KEVM/KVM execution, and RocksDB state storage.
kortana-validator: An isolated, high-security consensus signing daemon that holds the validator's private BLS12-381 consensus key and communicates with kortanad over a secure local IPC socket.
kortana-cli: The command-line administration utility used for key generation, wallet operations, staking transactions, and governance voting.
quorlinc: The native compiler for the Quorlin smart contract programming language.

32.7 Configuration & Data Directory

Node configuration in Kortana is managed via a clean, structured TOML document located by default at ~/.kortana/config.toml. The configuration schema is partitioned into discrete tables governing network identity, P2P transports, mempool rules, storage cache sizes, and RPC service endpoints.

Key configuration parameters include p2p.listen_port (default 30303), rpc.http_port (default 8545), rpc.max_batch_size (default 5 MB), storage.db_path (default ~/.kortana/data/), storage.block_cache_size_mb (default 8192 MB), and consensus.pacemaker_timeout_ms (default 4500 ms). Node operators can override any configuration variable using command-line flags or environment variables (prefixed with KORTANA_). All active data files—including RocksDB column families, Write-Ahead Logs, and runtime socket descriptors—are stored strictly within the specified data directory.