network

Orama Network - Distributed P2P Platform

A high-performance API Gateway and distributed platform built in Go. Provides a unified HTTP/HTTPS API for distributed SQL (RQLite), distributed caching (Olric), decentralized storage (IPFS), pub/sub messaging, and serverless WebAssembly execution.

Architecture: Modular Gateway / Edge Proxy following SOLID principles

Features

• 🔐 Authentication - Wallet signatures, API keys, JWT tokens
• 💾 Storage - IPFS-based decentralized file storage with encryption
• ⚡ Cache - Distributed cache with Olric (in-memory key-value)
• 🗄️ Database - RQLite distributed SQL with Raft consensus + Per-namespace SQLite databases
• 📡 Pub/Sub - Real-time messaging via LibP2P and WebSocket
• ⚙️ Serverless - WebAssembly function execution with host functions
• 🌐 HTTP Gateway - Unified REST API with automatic HTTPS (Let's Encrypt)
• 📦 Client SDK - Type-safe Go SDK for all services
• 🚀 App Deployments - Deploy React, Next.js, Go, Node.js apps with automatic domains
• 🗄️ SQLite Databases - Per-namespace isolated databases with IPFS backups

Application Deployments

Deploy full-stack applications with automatic domain assignment and namespace isolation.

Deploy a React App

# Build your app
cd my-react-app
npm run build

# Deploy to Orama Network
orama deploy static ./dist --name my-app

# Your app is now live at: https://my-app.orama.network

Deploy Next.js with SSR

cd my-nextjs-app

# Ensure next.config.js has: output: 'standalone'
npm run build
orama deploy nextjs . --name my-nextjs --ssr

# Live at: https://my-nextjs.orama.network

Deploy Go Backend

# Build for Linux (name binary 'app' for auto-detection)
GOOS=linux GOARCH=amd64 go build -o app main.go

# Deploy (must implement /health endpoint)
orama deploy go ./app --name my-api

# API live at: https://my-api.orama.network

Create SQLite Database

# Create database
orama db create my-database

# Create schema
orama db query my-database "CREATE TABLE users (id INT, name TEXT)"

# Insert data
orama db query my-database "INSERT INTO users VALUES (1, 'Alice')"

# Query data
orama db query my-database "SELECT * FROM users"

# Backup to IPFS
orama db backup my-database

Full-Stack Example

Deploy a complete app with React frontend, Go backend, and SQLite database:

# 1. Create database
orama db create myapp-db
orama db query myapp-db "CREATE TABLE users (id INT PRIMARY KEY, name TEXT)"

# 2. Deploy Go backend (connects to database)
GOOS=linux GOARCH=amd64 go build -o api main.go
orama deploy go ./api --name myapp-api

# 3. Deploy React frontend (calls backend API)
cd frontend && npm run build
orama deploy static ./dist --name myapp

# Access:
# Frontend: https://myapp.orama.network
# Backend: https://myapp-api.orama.network

📖 Full Guide: See Deployment Guide for complete documentation, examples, and best practices.

Quick Start

Local Development

# Build the project
make build

# Start 5-node development cluster
make dev

The cluster automatically performs health checks before declaring success.

Stop Development Environment

make stop

Testing Services

After running make dev, test service health using these curl requests:

Node Unified Gateways

Each node is accessible via a single unified gateway port:

# Node-1 (port 6001)
curl http://localhost:6001/health

# Node-2 (port 6002)
curl http://localhost:6002/health

# Node-3 (port 6003)
curl http://localhost:6003/health

# Node-4 (port 6004)
curl http://localhost:6004/health

# Node-5 (port 6005)
curl http://localhost:6005/health

Network Architecture

Unified Gateway Ports

Node-1:     localhost:6001  → /rqlite/http, /rqlite/raft, /cluster, /ipfs/api
Node-2:     localhost:6002  → Same routes
Node-3:     localhost:6003  → Same routes
Node-4:     localhost:6004  → Same routes
Node-5:     localhost:6005  → Same routes

Direct Service Ports (for debugging)

RQLite HTTP:     5001, 5002, 5003, 5004, 5005 (one per node)
RQLite Raft:     7001, 7002, 7003, 7004, 7005
IPFS API:        4501, 4502, 4503, 4504, 4505
IPFS Swarm:      4101, 4102, 4103, 4104, 4105
Cluster API:     9094, 9104, 9114, 9124, 9134
Internal Gateway: 6000
Olric Cache:     3320
Anon SOCKS:      9050

Development Commands

# Start full cluster (5 nodes + gateway)
make dev

# Check service status
orama dev status

# View logs
orama dev logs node-1           # Node-1 logs
orama dev logs node-1 --follow  # Follow logs in real-time
orama dev logs gateway --follow # Gateway logs

# Stop all services
orama stop

# Build binaries
make build

CLI Commands

Authentication

orama auth login            # Authenticate with wallet
orama auth status           # Check authentication
orama auth logout           # Clear credentials

Application Deployments

# Deploy applications
orama deploy static <path> --name myapp       # React, Vue, static sites
orama deploy nextjs <path> --name myapp --ssr # Next.js with SSR (requires output: 'standalone')
orama deploy go <path> --name myapp           # Go binaries (must have /health endpoint)
orama deploy nodejs <path> --name myapp       # Node.js apps (must have /health endpoint)

# Manage deployments
orama deployments list                        # List all deployments
orama deployments get <name>                  # Get deployment details
orama deployments logs <name> --follow        # View logs
orama deployments delete <name>               # Delete deployment
orama deployments rollback <name> --version 1 # Rollback to version

SQLite Databases

orama db create <name>                   # Create database
orama db query <name> "SELECT * FROM t"  # Execute SQL query
orama db list                            # List all databases
orama db backup <name>                   # Backup to IPFS
orama db backups <name>                  # List backups

Network Status

orama health                # Cluster health check
orama peers                 # List connected peers
orama status                # Network status

RQLite Operations

orama query "SELECT * FROM users"
orama query "CREATE TABLE users (id INTEGER PRIMARY KEY)"
orama transaction --file ops.json

Pub/Sub

orama pubsub publish <topic> <message>
orama pubsub subscribe <topic> 30s
orama pubsub topics

Serverless Functions (WASM)

Orama supports high-performance serverless function execution using WebAssembly (WASM). Functions are isolated, secure, and can interact with network services like the distributed cache.

1. Build Functions

Functions must be compiled to WASM. We recommend using TinyGo.

# Build example functions to examples/functions/bin/
./examples/functions/build.sh

2. Deployment

Deploy your compiled .wasm file to the network via the Gateway.

# Deploy a function
curl -X POST http://localhost:6001/v1/functions \
  -H "Authorization: Bearer <your_api_key>" \
  -F "name=hello-world" \
  -F "namespace=default" \
  -F "wasm=@./examples/functions/bin/hello.wasm"

3. Invocation

Trigger your function with a JSON payload. The function receives the payload via stdin and returns its response via stdout.

# Invoke via HTTP
curl -X POST http://localhost:6001/v1/functions/hello-world/invoke \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Developer"}'

4. Management

# List all functions in a namespace
curl http://localhost:6001/v1/functions?namespace=default

# Delete a function
curl -X DELETE http://localhost:6001/v1/functions/hello-world?namespace=default

Production Deployment

Prerequisites

• Ubuntu 22.04+ or Debian 12+
• amd64 or arm64 architecture
• 4GB RAM, 50GB SSD, 2 CPU cores

Required Ports

External (must be open in firewall):

• 80 - HTTP (ACME/Let's Encrypt certificate challenges)
• 443 - HTTPS (Main gateway API endpoint)
• 4101 - IPFS Swarm (peer connections)
• 7001 - RQLite Raft (cluster consensus)

Internal (bound to localhost, no firewall needed):

• 4501 - IPFS API
• 5001 - RQLite HTTP API
• 6001 - Unified Gateway
• 8080 - IPFS Gateway
• 9050 - Anyone SOCKS5 proxy
• 9094 - IPFS Cluster API
• 3320/3322 - Olric Cache

Anyone Relay Mode (optional, for earning rewards):

• 9001 - Anyone ORPort (relay traffic, must be open externally)

Anyone Network Integration

Orama Network integrates with the Anyone Protocol for anonymous routing. By default, nodes run as clients (consuming the network). Optionally, you can run as a relay operator to earn rewards.

Client Mode (Default):

• Routes traffic through Anyone network for anonymity
• SOCKS5 proxy on localhost:9050
• No rewards, just consumes network

Relay Mode (Earn Rewards):

• Provide bandwidth to the Anyone network
• Earn $ANYONE tokens as a relay operator
• Requires 100 $ANYONE tokens in your wallet
• Requires ORPort (9001) open to the internet

# Install as relay operator (earn rewards)
sudo orama install --vps-ip <IP> --domain <domain> \
  --anyone-relay \
  --anyone-nickname "MyRelay" \
  --anyone-contact "operator@email.com" \
  --anyone-wallet "0x1234...abcd"

# With exit relay (legal implications apply)
sudo orama install --vps-ip <IP> --domain <domain> \
  --anyone-relay \
  --anyone-exit \
  --anyone-nickname "MyExitRelay" \
  --anyone-contact "operator@email.com" \
  --anyone-wallet "0x1234...abcd"

# Migrate existing Anyone installation
sudo orama install --vps-ip <IP> --domain <domain> \
  --anyone-relay \
  --anyone-migrate \
  --anyone-nickname "MyRelay" \
  --anyone-contact "operator@email.com" \
  --anyone-wallet "0x1234...abcd"

Important: After installation, register your relay at dashboard.anyone.io to start earning rewards.

Installation

macOS (Homebrew):

brew install DeBrosOfficial/tap/orama

Linux (Debian/Ubuntu):

# Download and install the latest .deb package
curl -sL https://github.com/DeBrosOfficial/network/releases/latest/download/orama_$(curl -s https://api.github.com/repos/DeBrosOfficial/network/releases/latest | grep tag_name | cut -d '"' -f 4 | tr -d 'v')_linux_amd64.deb -o orama.deb
sudo dpkg -i orama.deb

From Source:

go install github.com/DeBrosOfficial/network/cmd/cli@latest

Setup (after installation):

sudo orama install --interactive

Service Management

# Status
orama status

# Control services
sudo orama start
sudo orama stop
sudo orama restart

# View logs
orama logs node --follow
orama logs gateway --follow
orama logs ipfs --follow

Upgrade

# Upgrade to latest version
sudo orama upgrade --interactive

Configuration

All configuration lives in ~/.orama/:

• configs/node.yaml - Node configuration
• configs/gateway.yaml - Gateway configuration
• configs/olric.yaml - Cache configuration
• secrets/ - Keys and certificates
• data/ - Service data directories

Troubleshooting

Services Not Starting

# Check status
systemctl status debros-node

# View logs
journalctl -u debros-node -f

# Check log files
tail -f /home/debros/.orama/logs/node.log

Port Conflicts

# Check what's using specific ports
sudo lsof -i :443   # HTTPS Gateway
sudo lsof -i :7001  # TCP/SNI Gateway
sudo lsof -i :6001  # Internal Gateway

RQLite Cluster Issues

# Connect to RQLite CLI
rqlite -H localhost -p 5001

# Check cluster status
.nodes
.status
.ready

# Check consistency level
.consistency

Reset Installation

# Production reset (⚠️ DESTROYS DATA)
sudo orama uninstall
sudo rm -rf /home/debros/.orama
sudo orama install

HTTP Gateway API

Main Gateway Endpoints

• GET /health - Health status
• GET /v1/status - Full status
• GET /v1/version - Version info
• POST /v1/rqlite/exec - Execute SQL
• POST /v1/rqlite/query - Query database
• GET /v1/rqlite/schema - Get schema
• POST /v1/pubsub/publish - Publish message
• GET /v1/pubsub/topics - List topics
• GET /v1/pubsub/ws?topic=<name> - WebSocket subscribe
• POST /v1/functions - Deploy function (multipart/form-data)
• POST /v1/functions/{name}/invoke - Invoke function
• GET /v1/functions - List functions
• DELETE /v1/functions/{name} - Delete function
• GET /v1/functions/{name}/logs - Get function logs

See openapi/gateway.yaml for complete API specification.

Documentation

• Deployment Guide - Deploy React, Next.js, Go apps and manage databases
• Architecture Guide - System architecture and design patterns
• Client SDK - Go SDK documentation and examples
• Gateway API - Complete HTTP API reference
• Security Deployment - Production security hardening
• Testing Plan - Comprehensive testing strategy and implementation

Resources

• RQLite Documentation
• IPFS Documentation
• LibP2P Documentation
• WebAssembly
• GitHub Repository
• Issue Tracker

Project Structure

network/
├── cmd/              # Binary entry points
│   ├── cli/         # CLI tool
│   ├── gateway/     # HTTP Gateway
│   ├── node/        # P2P Node
│   └── rqlite-mcp/  # RQLite MCP server
├── pkg/              # Core packages
│   ├── gateway/     # Gateway implementation
│   │   └── handlers/ # HTTP handlers by domain
│   ├── client/      # Go SDK
│   ├── serverless/  # WASM engine
│   ├── rqlite/      # Database ORM
│   ├── contracts/   # Interface definitions
│   ├── httputil/    # HTTP utilities
│   └── errors/      # Error handling
├── docs/            # Documentation
├── e2e/             # End-to-end tests
└── examples/        # Example code

Contributing

Contributions are welcome! This project follows:

• SOLID Principles - Single responsibility, open/closed, etc.
• DRY Principle - Don't repeat yourself
• Clean Architecture - Clear separation of concerns
• Test Coverage - Unit and E2E tests required

See our architecture docs for design patterns and guidelines.