orama-vault/docs/DEPLOYMENT.md

Orama Vault -- Deployment Guide

Prerequisites

• Zig 0.14.0+ (specified in build.zig.zon as minimum_zig_version). Zig 0.15+ recommended for the latest std library improvements.
• Linux x86_64 target for production nodes.
• macOS (arm64 or x86_64) for local development and testing.

No external dependencies. The guardian is a single static binary with no runtime library requirements (musl libc, statically linked).

---

Building

Production Build (Linux target)

From the project root:

zig build -Dtarget=x86_64-linux-musl -Doptimize=ReleaseSafe

This produces:

zig-out/bin/vault-guardian

The binary is statically linked against musl libc, so it runs on any Linux x86_64 system regardless of glibc version.

Build options:

Flag	Description
-Dtarget=x86_64-linux-musl	Cross-compile for Linux x86_64 with musl (static)
-Doptimize=ReleaseSafe	Optimized with safety checks (recommended for production)
-Doptimize=ReleaseFast	Maximum optimization, no safety checks
-Doptimize=Debug	Debug build with full debug info

Development Build (native)

zig build

Produces a debug binary for the host platform at zig-out/bin/vault-guardian.

Running Tests

zig build test

Runs all unit tests across every module (SSS, crypto, storage, auth, membership, peer protocol, server). The test entry point is src/tests.zig, which imports all test modules via comptime.

Run Locally

zig build run -- --data-dir /tmp/vault-test --port 7500 --bind 127.0.0.1

Or after building:

./zig-out/bin/vault-guardian --data-dir /tmp/vault-test --port 7500 --bind 127.0.0.1

---

CLI Arguments

Usage: vault-guardian [OPTIONS]

Orama Vault Guardian -- distributed secret share storage

Options:
  --config <path>   Path to config file (default: /opt/orama/.orama/data/vault/vault.yaml)
  --data-dir <path> Override data directory
  --port <port>     Override client port (default: 7500)
  --bind <addr>     Override bind address (default: 0.0.0.0)
  --help, -h        Show this help
  --version, -v     Show version

CLI arguments override config file values.

---

Configuration

The guardian reads a config file from --config (default: /opt/orama/.orama/data/vault/vault.yaml).

Note: YAML parsing is not yet implemented (Phase 2). The config loader currently returns defaults regardless of file contents. All configuration must be done via CLI arguments for now.

Config Fields

Field	Default	Description
listen_address	0.0.0.0	Address to bind both client and peer listeners
client_port	7500	Client-facing HTTP port
peer_port	7501	Guardian-to-guardian binary protocol port
data_dir	/opt/orama/.orama/data/vault	Directory for share storage
rqlite_url	http://127.0.0.1:4001	RQLite endpoint for node discovery

---

Data Directory Setup

The guardian creates the data directory on startup if it does not exist. The directory structure:

/opt/orama/.orama/data/vault/
    shares/
        <identity_hash_hex>/
            share.bin       -- Encrypted share data
            version         -- Monotonic version counter
            checksum.bin    -- HMAC-SHA256 integrity checksum

Permissions

The data directory must be writable by the guardian process. With the systemd service, only /opt/orama/.orama/data/vault is writable (ReadWritePaths).

# Create data directory
sudo mkdir -p /opt/orama/.orama/data/vault
sudo chown orama:orama /opt/orama/.orama/data/vault
sudo chmod 700 /opt/orama/.orama/data/vault

---

Systemd Service

The project includes a systemd service file at systemd/orama-vault.service:

[Unit]
Description=Orama Vault Guardian
Documentation=https://github.com/orama-network/debros
After=network.target
PartOf=orama-node.service

[Service]
Type=simple
ExecStart=/opt/orama/bin/vault-guardian --config /opt/orama/.orama/data/vault/vault.yaml
Restart=on-failure
RestartSec=5s

# Security hardening
PrivateTmp=yes
ProtectSystem=strict
ReadWritePaths=/opt/orama/.orama/data/vault
NoNewPrivileges=yes

# Allow mlock for secure memory
LimitMEMLOCK=67108864

# Resource limits
MemoryMax=512M

[Install]
WantedBy=multi-user.target

Installation

# Copy binary
sudo cp zig-out/bin/vault-guardian /opt/orama/bin/vault-guardian
sudo chmod 755 /opt/orama/bin/vault-guardian

# Copy service file
sudo cp systemd/orama-vault.service /etc/systemd/system/orama-vault.service

# Reload systemd
sudo systemctl daemon-reload

# Enable and start
sudo systemctl enable orama-vault
sudo systemctl start orama-vault

# Check status
sudo systemctl status orama-vault

Service Dependencies

The service is PartOf=orama-node.service, meaning:

• When orama-node.service is stopped, orama-vault is also stopped.
• When orama-node.service is restarted, orama-vault is also restarted.
• After=network.target ensures the network stack is up before the guardian starts.

Restart Behavior

• Restart=on-failure: The guardian restarts if it exits with a non-zero status.
• RestartSec=5s: Wait 5 seconds between restarts.
• The guardian generates a new server secret on each start, which invalidates all existing session tokens. This is intentional -- sessions should not survive restarts.

---

Firewall Rules

UFW Configuration

# Client port: accessible from WireGuard overlay and optionally from gateway
sudo ufw allow from 10.0.0.0/24 to any port 7500 proto tcp comment "vault-guardian client"

# Peer port: WireGuard overlay ONLY
sudo ufw allow from 10.0.0.0/24 to any port 7501 proto tcp comment "vault-guardian peer"

Port Summary

Port	Protocol	Interface	Purpose
7500	TCP	WireGuard (10.0.0.x)	Client-facing HTTP API
7501	TCP	WireGuard (10.0.0.x) only	Guardian-to-guardian binary protocol

Port 7501 must NEVER be exposed on the public interface. The peer protocol has no authentication beyond WireGuard -- it trusts that only authorized nodes can reach it.

Port 7500 may be exposed on the public interface if the node runs without the Orama gateway reverse proxy, but this is not recommended for production.

---

Cross-Compilation

Zig's cross-compilation makes it trivial to build for any target:

# Linux x86_64 (production)
zig build -Dtarget=x86_64-linux-musl -Doptimize=ReleaseSafe

# Linux aarch64 (ARM servers)
zig build -Dtarget=aarch64-linux-musl -Doptimize=ReleaseSafe

# macOS x86_64
zig build -Dtarget=x86_64-macos -Doptimize=ReleaseSafe

# macOS aarch64 (Apple Silicon)
zig build -Dtarget=aarch64-macos -Doptimize=ReleaseSafe

All targets produce a single static binary. No runtime dependencies to install on the target system.

---

Deployment to Orama Network Nodes

The vault guardian is deployed alongside other Orama services. The typical deployment workflow:

1. Build the binary on the development machine (cross-compile for Linux).
2. Copy the binary to the target node via scp or the orama CLI deploy tool.
3. Place the binary at /opt/orama/bin/vault-guardian.
4. Ensure the systemd service is installed and enabled.
5. Restart the service: sudo systemctl restart orama-vault.

For rolling upgrades across the cluster, follow the standard Orama network rolling upgrade protocol: upgrade one node at a time, verify health between each node.

Health Verification After Deploy

# Check systemd service
sudo systemctl status orama-vault

# Check health endpoint
curl http://127.0.0.1:7500/v1/vault/health

# Expected response:
# {"status":"ok","version":"0.1.0"}

# Check status endpoint
curl http://127.0.0.1:7500/v1/vault/status

---

Environment-Specific Notes

Development / Local Testing

# Run with a local data directory, non-default port
./zig-out/bin/vault-guardian --data-dir /tmp/vault-dev --port 7500 --bind 127.0.0.1

The guardian runs in single-node mode when it cannot reach RQLite. This is normal for local development.

Staging / Testnet

Same binary, deployed to testnet nodes. Use the standard config path:

vault-guardian --config /opt/orama/.orama/data/vault/vault.yaml

Production / Mainnet

• Ensure WireGuard is up and peers are connected before starting the guardian.
• Ensure RQLite is running and healthy (the guardian queries it for node discovery).
• Verify firewall rules restrict port 7501 to WireGuard interfaces only.
• Monitor via the health endpoint and systemd journal.