# Getting Started as a Node Operator

Node operators are the backbone of the Orama Network. By running a node, you contribute compute, storage, and bandwidth to the decentralized infrastructure and earn rewards in return. This guide covers what operators do, what you need, and how to join the network.

## What Operators Do

As a node operator, your server becomes part of the Orama mesh network. Your node will:

- **Route traffic** through the API gateway for applications deployed on the network
- **Store data** in distributed databases (RQLite) and cache layers (Olric)
- **Host files** on IPFS with cluster-level replication
- **Execute functions** in the WASM serverless runtime
- **Relay messages** through the PubSub system
- **Serve DNS** if configured as a nameserver node (CoreDNS)
- **Run an Anyone relay** if configured, earning dual rewards

All inter-node communication happens over an encrypted WireGuard mesh network on the `10.0.0.0/24` subnet.

## Hardware Requirements

| Resource | Minimum |
|----------|---------|
| CPU | 4 vCPUs |
| RAM | 8 GB |
| Storage | 160 GB SSD |
| Network | 1 Gbps, unmetered or high bandwidth cap |
| OS | Ubuntu 22.04 LTS |

A stable network connection with low latency is important for Raft consensus and mesh connectivity.

## Rewards

Node operators earn dual rewards for contributing resources:

- **$ORAMA** -- native network token
- **$ANYONE** -- earned through the Anyone privacy relay running on every node

Rewards are distributed based on uptime, performance, and the volume of traffic your node handles.

## Getting the CLI Binary

The `orama` CLI is a single Go binary. It is provided to accepted operators as a pre-compiled binary for Linux amd64. The binary is placed at `/usr/local/bin/orama` during installation.

The CLI is used both for initial node setup and ongoing management. All node operations require `sudo`.

## Joining the Network

To become an operator, you need:

1. A VPS meeting the hardware requirements above
2. An invite token (generated by an existing node in the cluster)
3. The `orama` binary on your VPS

### Step 1: Get an Invite Token

An existing cluster node generates a single-use invite token:

```bash
# On an existing node (requires sudo)
sudo orama node invite --expiry 24h
```

Tokens are single-use and expire after the specified duration (default: 1 hour).

### Step 2: Install the Node

**Genesis node (first node, creates a new cluster):**

```bash
sudo orama node install \
  --vps-ip <PUBLIC_IP> \
  --domain <BASE_DOMAIN> \
  --base-domain <BASE_DOMAIN> \
  --nameserver
```

**Nameserver node (joins existing cluster):**

```bash
sudo orama node install \
  --join http://<GENESIS_IP> --token <TOKEN> \
  --vps-ip <PUBLIC_IP> \
  --domain <BASE_DOMAIN> \
  --base-domain <BASE_DOMAIN> \
  --nameserver
```

**Regular node (joins existing cluster, domain is auto-generated):**

```bash
sudo orama node install \
  --join http://<GENESIS_IP> --token <TOKEN> \
  --vps-ip <PUBLIC_IP> \
  --base-domain <BASE_DOMAIN>
```

**Regular node with Anyone relay:**

```bash
sudo orama node install \
  --join http://<GENESIS_IP> --token <TOKEN> \
  --vps-ip <PUBLIC_IP> \
  --base-domain <BASE_DOMAIN> \
  --anyone-relay \
  --anyone-nickname <NAME> \
  --anyone-wallet <ETH_ADDRESS> \
  --anyone-contact "<EMAIL_OR_TELEGRAM>"
```

### Install Flags

| Flag | Required | Description |
|------|----------|-------------|
| `--vps-ip` | Yes | Public IP address of this VPS |
| `--base-domain` | Yes | Base domain for deployment routing (e.g., `orama-devnet.network`) |
| `--domain` | No | Domain for HTTPS. Auto-generated for non-nameserver nodes (e.g., `node-a3f8k2.orama-devnet.network`) |
| `--nameserver` | No | Make this node a nameserver (runs CoreDNS + Caddy) |
| `--join` | No | URL of an existing node to join (e.g., `http://1.2.3.4`) |
| `--token` | No | Invite token from `orama node invite` on an existing node |
| `--force` | No | Force reconfiguration even if already installed |
| `--dry-run` | No | Show what would be done without making changes |
| `--skip-checks` | No | Skip minimum resource checks (RAM/CPU) |
| `--skip-firewall` | No | Skip UFW firewall setup (for users who manage their own firewall) |

#### Anyone Relay Flags

| Flag | Default | Description |
|------|---------|-------------|
| `--anyone-relay` | `false` | Run as Anyone relay operator (earn rewards) |
| `--anyone-client` | `false` | Install Anyone as client-only (SOCKS5 proxy on port 9050, no relay) |
| `--anyone-exit` | `false` | Run as exit relay (requires `--anyone-relay`, legal implications) |
| `--anyone-migrate` | `false` | Migrate existing Anyone installation into Orama Network |
| `--anyone-nickname` | -- | Relay nickname (1-19 alphanumeric chars) |
| `--anyone-wallet` | -- | Ethereum wallet address for rewards |
| `--anyone-contact` | -- | Contact info (email or @telegram) |
| `--anyone-orport` | `9001` | ORPort for the relay |
| `--anyone-family` | -- | Comma-separated fingerprints of other relays you operate |
| `--anyone-bandwidth` | `30` | Limit relay to N% of VPS bandwidth (0 = unlimited, runs speedtest) |
| `--anyone-accounting` | `0` | Monthly data cap for relay in GB (0 = unlimited) |

## What the Installer Does

The `orama node install` command configures the entire node automatically:

1. Validates system requirements (RAM, CPU, disk)
2. Generates a WireGuard keypair and establishes mesh tunnels to all peers
3. Configures and starts RQLite (distributed SQL)
4. Configures and starts Olric (distributed cache)
5. Configures and starts IPFS + IPFS Cluster (distributed storage)
6. Configures and starts the API gateway
7. If `--nameserver`: configures CoreDNS and Caddy for DNS and TLS
8. If `--anyone-relay`: configures the Anyone relay daemon
9. Sets up systemd services with dependency ordering
10. Configures the UFW firewall (unless `--skip-firewall`)
11. Registers the node with the cluster

## Node Management

After installation, use these commands to manage your node:

```bash
# Check service status
sudo orama node status

# Start all services
sudo orama node start

# Stop all services (masks services to prevent auto-restart)
sudo orama node stop
sudo orama node stop --force    # bypass quorum safety check

# Restart all services
sudo orama node restart
sudo orama node restart --force  # bypass quorum safety check

# Run diagnostic checks
sudo orama node doctor

# View service logs
sudo orama node logs <service>
# Service aliases: node, ipfs, cluster, gateway, olric

# Output node health data as JSON
sudo orama node report --json
```

### Additional Node Commands

| Command | Description |
|---------|-------------|
| `orama node uninstall` | Remove all Orama services from this node |
| `orama node upgrade --restart` | Upgrade binary and restart services |
| `orama node push --env <env>` | Push binary archive to remote nodes |
| `orama node rollout --env <env>` | Build, push, and rolling upgrade all nodes |
| `orama node clean --env <env>` | Wipe remote nodes for reinstallation |
| `orama node invite --expiry <duration>` | Generate an invite token for new nodes |
| `orama node recover-raft --leader <ip>` | Recover RQLite cluster from split-brain |
| `orama node migrate` | Migrate from an older installation layout |

## Upgrading

Upgrades are performed via binary replacement with a rolling restart:

```bash
# Upgrade this node (extracts new binary and restarts services)
sudo orama node upgrade --restart
```

For multi-node clusters, upgrade one node at a time and verify health between each:

```bash
# Check cluster health
orama monitor report --env devnet

# Check single node health
orama monitor report --env devnet --node <IP>
```

See [Upgrades](/docs/operator/upgrades) for the full rolling upgrade procedure.

## Monitoring

The `orama monitor` command provides real-time cluster monitoring from your local machine:

```bash
# Interactive TUI
orama monitor --env devnet

# Cluster overview (one-shot)
orama monitor cluster --env devnet

# Per-node health details
orama monitor node --env devnet

# Service status across the cluster
orama monitor service --env devnet

# WireGuard mesh connectivity
orama monitor mesh --env devnet

# DNS health
orama monitor dns --env devnet

# Namespace usage summary
orama monitor namespaces --env devnet

# Active alerts
orama monitor alerts --env devnet

# Full cluster report
orama monitor report --env devnet
```

All monitor subcommands support `--json` for machine-readable output and `--node <IP>` to filter to a specific node.

The `orama inspect` command provides deeper SSH-based health checks with optional AI analysis:

```bash
# Inspect all subsystems
orama inspect --env devnet

# Inspect specific subsystem
orama inspect --env devnet --subsystem wg

# With AI analysis of failures
orama inspect --env devnet --ai
```

Available subsystems for inspect: `rqlite`, `olric`, `ipfs`, `dns`, `wg`, `system`, `network`, `anyone`, `all`.

## Next Steps

- [Node Setup](/docs/operator/node-setup) -- Detailed setup instructions
- [WireGuard](/docs/operator/wireguard) -- Mesh network documentation
- [Nameserver](/docs/operator/nameserver) -- CoreDNS nameserver setup
- [Monitoring](/docs/operator/monitoring) -- Health monitoring and alerting
- [Upgrades](/docs/operator/upgrades) -- Rolling upgrade procedures
- [Troubleshooting](/docs/operator/troubleshooting) -- Common issues and fixes
