# 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. The `orama` CLI on your local machine
3. RootWallet desktop app (for SSH key management and wallet authentication)

### Setting Up Your First Node (Genesis)

The first node creates a new cluster. Run this from your **local machine** (not the VPS):

```bash
orama node setup \
  --ip <VPS_IP> \
  --password '<VPS_PASSWORD>' \
  --env devnet \
  --base-domain <BASE_DOMAIN> \
  --role nameserver \
  --genesis
```

This single command:
1. Creates an SSH key in your RootWallet vault
2. Installs the SSH key on the VPS (using the password once)
3. Uploads the binary archive
4. Installs and starts all services
5. Updates your local environment config to point to this node

After genesis, authenticate with the new cluster:

```bash
orama auth login
```

### Adding More Nodes

Once the genesis node is running and you're authenticated, add more nodes with one command:

```bash
# Add a nameserver node
orama node setup \
  --ip <VPS_IP> \
  --password '<VPS_PASSWORD>' \
  --env devnet \
  --base-domain <BASE_DOMAIN> \
  --role nameserver

# Add a regular node
orama node setup \
  --ip <VPS_IP> \
  --password '<VPS_PASSWORD>' \
  --env devnet \
  --base-domain <BASE_DOMAIN>

# Add a node with Anyone relay
orama node setup \
  --ip <VPS_IP> \
  --password '<VPS_PASSWORD>' \
  --env devnet \
  --base-domain <BASE_DOMAIN> \
  --anyone-relay
```

The setup command automatically:
- Creates a unique SSH key for the node in RootWallet
- Installs the key on the VPS (password is used once, then discarded)
- Requests an invite token from the cluster (using your wallet authentication)
- Uploads binaries and runs the full installation
- Joins the node to the cluster

The `--password` flag is only needed for the initial SSH key installation. After that, all SSH access uses the RootWallet key.

### Setup Flags

| Flag | Required | Description |
|------|----------|-------------|
| `--ip` | Yes | Public IP address of the VPS |
| `--password` | No | One-time VPS password for SSH key installation |
| `--env` | No | Target environment (default: active environment) |
| `--base-domain` | Yes | Base domain for the network (e.g., `orama-devnet.network`) |
| `--role` | No | `node` (default) or `nameserver` |
| `--user` | No | SSH user (default: `root`) |
| `--gateway` | No | Gateway URL override for invite tokens |
| `--genesis` | No | Create a new cluster (first node only) |
| `--anyone-relay` | No | Run as Anyone relay operator |

#### 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, your node is automatically registered with your wallet. Use these unified commands from your local machine:

```bash
# List all your nodes
orama nodes --env devnet

# Check health of all your nodes
orama status --env devnet

# SSH into any node
orama ssh <IP>

# Rolling upgrade all your nodes
orama rollout --env devnet
```

See [Node Management](/docs/operator/node-management) for the full guide.

### On-Node Commands

These commands run directly on a VPS with `sudo`:

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

# Start/stop/restart all services
sudo orama node start
sudo orama node stop
sudo orama node restart

# Run diagnostic checks
sudo orama node doctor

# View service logs
sudo orama node logs <service>

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

## Upgrading

Deploy new code to all your nodes with one command:

```bash
orama build                    # Build the binary archive
orama rollout --env devnet     # Push + rolling upgrade (followers first, leader last)
```

Or upgrade a single node directly on the VPS:

```bash
sudo orama node upgrade --restart
```

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

## Monitoring

Quick health check of all your nodes:

```bash
orama status --env devnet
```

For detailed monitoring with cross-node analysis and alerts:

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

# Full cluster report (JSON)
orama monitor report --env devnet

# Active alerts only
orama monitor alerts --env devnet
```

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

See [Monitoring](/docs/operator/monitoring) for the full monitoring guide.

## Next Steps

- [Node Management](/docs/operator/node-management) -- Unified commands: `orama nodes`, `ssh`, `status`, `rollout`
- [Node Setup](/docs/operator/node-setup) -- Detailed VPS installation 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
