DeBros/network
4
0
Fork 0
mirror of https://github.com/DeBrosOfficial/network.git synced 2026-01-30 05:23:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

updated docs

Browse Source
This commit is contained in:
anonpenguin23 2026-01-22 18:55:00 +02:00
parent 5547c8ccb5
commit ec66213e2e
7 changed files with 1129 additions and 1993 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

151
README.md
View File

@ -9,11 +9,95 @@ A high-performance API Gateway and distributed platform built in Go. Provides a
- **🔐 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
- **🗄️ 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
```bash
# 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
```bash
cd my-nextjs-app
npm run build
orama deploy nextjs . --name my-nextjs --ssr
# Live at: https://my-nextjs.orama.network
```
### Deploy Go Backend
```bash
# Build for Linux
GOOS=linux GOARCH=amd64 go build -o api main.go
# Deploy
orama deploy go ./api --name my-api
# API live at: https://my-api.orama.network
```
### Create SQLite Database
```bash
# 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:
```bash
# 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](docs/DEPLOYMENT_GUIDE.md) for complete documentation, examples, and best practices.
## Quick Start
@ -108,36 +192,63 @@ make build
## CLI Commands
### Authentication
```bash
orama auth login # Authenticate with wallet
orama auth status # Check authentication
orama auth logout # Clear credentials
```
### Application Deployments
```bash
# Deploy applications
orama deploy static <path> --name myapp # React, Vue, static sites
orama deploy nextjs <path> --name myapp --ssr # Next.js with SSR
orama deploy go <path> --name myapp # Go binaries
orama deploy nodejs <path> --name myapp # Node.js apps
# 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
```bash
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
```bash
./bin/orama health # Cluster health check
./bin/orama peers # List connected peers
./bin/orama status # Network status
orama health # Cluster health check
orama peers # List connected peers
orama status # Network status
```
### Database Operations
### RQLite Operations
```bash
./bin/orama query "SELECT * FROM users"
./bin/orama query "CREATE TABLE users (id INTEGER PRIMARY KEY)"
./bin/orama transaction --file ops.json
orama query "SELECT * FROM users"
orama query "CREATE TABLE users (id INTEGER PRIMARY KEY)"
orama transaction --file ops.json
```
### Pub/Sub
```bash
./bin/orama pubsub publish <topic> <message>
./bin/orama pubsub subscribe <topic> 30s
./bin/orama pubsub topics
```
### Authentication
```bash
./bin/orama auth login
./bin/orama auth status
./bin/orama auth logout
orama pubsub publish <topic> <message>
orama pubsub subscribe <topic> 30s
orama pubsub topics
```
## Serverless Functions (WASM)
@ -331,10 +442,12 @@ See `openapi/gateway.yaml` for complete API specification.
## Documentation
- **[Deployment Guide](docs/DEPLOYMENT_GUIDE.md)** - Deploy React, Next.js, Go apps and manage databases
- **[Architecture Guide](docs/ARCHITECTURE.md)** - System architecture and design patterns
- **[Client SDK](docs/CLIENT_SDK.md)** - Go SDK documentation and examples
- **[Gateway API](docs/GATEWAY_API.md)** - Complete HTTP API reference
- **[Security Deployment](docs/SECURITY_DEPLOYMENT_GUIDE.md)** - Production security hardening
- **[Testing Plan](docs/TESTING_PLAN.md)** - Comprehensive testing strategy and implementation
## Resources

50
cmd/cli/main.go
View File

@ -76,6 +76,16 @@ func main() {
case "auth":
cli.HandleAuthCommand(args)
// Deployment commands
case "deploy":
cli.HandleDeployCommand(args)
case "deployments":
cli.HandleDeploymentsCommand(args)
// Database commands
case "db":
cli.HandleDBCommand(args)
// Help
case "help", "--help", "-h":
showHelp()
@ -132,19 +142,51 @@ func showHelp() {
fmt.Printf(" auth status - Show detailed auth info\n")
fmt.Printf(" auth help - Show auth command help\n\n")
fmt.Printf("📦 Deployments:\n")
fmt.Printf(" deploy static <path> - Deploy a static site (React, Vue, etc.)\n")
fmt.Printf(" deploy nextjs <path> - Deploy a Next.js application\n")
fmt.Printf(" deploy go <path> - Deploy a Go backend\n")
fmt.Printf(" deploy nodejs <path> - Deploy a Node.js backend\n")
fmt.Printf(" deployments list - List all deployments\n")
fmt.Printf(" deployments get <name> - Get deployment details\n")
fmt.Printf(" deployments logs <name> - View deployment logs\n")
fmt.Printf(" deployments delete <name> - Delete a deployment\n")
fmt.Printf(" deployments rollback <name> - Rollback to previous version\n\n")
fmt.Printf("🗄️ Databases:\n")
fmt.Printf(" db create <name> - Create a SQLite database\n")
fmt.Printf(" db query <name> \"<sql>\" - Execute SQL query\n")
fmt.Printf(" db list - List all databases\n")
fmt.Printf(" db backup <name> - Backup database to IPFS\n")
fmt.Printf(" db backups <name> - List database backups\n\n")
fmt.Printf("Global Flags:\n")
fmt.Printf(" -f, --format <format> - Output format: table, json (default: table)\n")
fmt.Printf(" -t, --timeout <duration> - Operation timeout (default: 30s)\n")
fmt.Printf(" --help, -h - Show this help message\n\n")
fmt.Printf("Examples:\n")
fmt.Printf(" # Deploy a React app\n")
fmt.Printf(" cd my-react-app && npm run build\n")
fmt.Printf(" orama deploy static ./dist --name my-app\n\n")
fmt.Printf(" # Deploy a Next.js app with SSR\n")
fmt.Printf(" cd my-nextjs-app && npm run build\n")
fmt.Printf(" orama deploy nextjs . --name my-nextjs --ssr\n\n")
fmt.Printf(" # Create and use a database\n")
fmt.Printf(" orama db create my-db\n")
fmt.Printf(" orama db query my-db \"CREATE TABLE users (id INT, name TEXT)\"\n")
fmt.Printf(" orama db query my-db \"INSERT INTO users VALUES (1, 'Alice')\"\n\n")
fmt.Printf(" # Manage deployments\n")
fmt.Printf(" orama deployments list\n")
fmt.Printf(" orama deployments get my-app\n")
fmt.Printf(" orama deployments logs my-app --follow\n\n")
fmt.Printf(" # First node (creates new cluster)\n")
fmt.Printf(" sudo orama install --vps-ip 203.0.113.1 --domain node-1.orama.network\n\n")
fmt.Printf(" # Join existing cluster\n")
fmt.Printf(" sudo orama install --vps-ip 203.0.113.2 --domain node-2.orama.network \\\n")
fmt.Printf(" --peers /ip4/203.0.113.1/tcp/4001/p2p/12D3KooW... --cluster-secret <hex>\n\n")
fmt.Printf(" # Service management\n")
fmt.Printf(" orama status\n")
fmt.Printf(" orama logs node --follow\n")

897
docs/DEPLOYMENT_GUIDE.md Normal file
View File

@ -0,0 +1,897 @@
# Orama Network Deployment Guide
Complete guide for deploying applications and managing databases on Orama Network.
## Table of Contents
- [Overview](#overview)
- [Authentication](#authentication)
- [Deploying Static Sites (React, Vue, etc.)](#deploying-static-sites)
- [Deploying Next.js Applications](#deploying-nextjs-applications)
- [Deploying Go Backends](#deploying-go-backends)
- [Deploying Node.js Backends](#deploying-nodejs-backends)
- [Managing SQLite Databases](#managing-sqlite-databases)
- [How Domains Work](#how-domains-work)
- [Full-Stack Application Example](#full-stack-application-example)
- [Managing Deployments](#managing-deployments)
- [Troubleshooting](#troubleshooting)
---
## Overview
Orama Network provides a decentralized platform for deploying web applications and managing databases. Each deployment:
- **Gets a unique domain** automatically (e.g., `myapp.orama.network`)
- **Isolated per namespace** - your data and apps are completely separate from others
- **Served from IPFS** (static) or **runs as a process** (dynamic apps)
- **Fully managed** - automatic health checks, restarts, and logging
### Supported Deployment Types
| Type | Description | Use Case | Domain Example |
|------|-------------|----------|----------------|
| **Static** | HTML/CSS/JS files served from IPFS | React, Vue, Angular, plain HTML | `myapp.orama.network` |
| **Next.js** | Next.js with SSR support | Full-stack Next.js apps | `myapp.orama.network` |
| **Go** | Compiled Go binaries | REST APIs, microservices | `api.orama.network` |
| **Node.js** | Node.js applications | Express APIs, TypeScript backends | `backend.orama.network` |
---
## Authentication
Before deploying, authenticate with your wallet:
```bash
# Authenticate
orama auth login
# Check authentication status
orama auth whoami
```
Your API key is stored securely and used for all deployment operations.
---
## Deploying Static Sites
Deploy static sites built with React, Vue, Angular, or any static site generator.
### React/Vite Example
```bash
# 1. Build your React app
cd my-react-app
npm run build
# 2. Deploy the build directory
orama deploy static ./dist --name my-react-app --domain repoanalyzer.ai
# Output:
# 📦 Creating tarball from ./dist...
# ☁️ Uploading to Orama Network...
#
# ✅ Deployment successful!
#
# Name: my-react-app
# Type: static
# Status: active
# Version: 1
# Content CID: QmXxxx...
#
# URLs:
# • https://my-react-app.orama.network
```
### What Happens Behind the Scenes
1. **Tarball Creation**: CLI automatically creates a `.tar.gz` from your directory
2. **IPFS Upload**: Files are uploaded to IPFS and pinned across the network
3. **DNS Record**: A DNS record is created pointing `my-react-app.orama.network` to the gateway
4. **Instant Serving**: Your app is immediately accessible via the URL
### Features
- ✅ **SPA Routing**: Unknown routes automatically serve `/index.html` (perfect for React Router)
- ✅ **Correct Content-Types**: Automatically detects and serves `.html`, `.css`, `.js`, `.json`, `.png`, etc.
- ✅ **Caching**: `Cache-Control: public, max-age=3600` headers for optimal performance
- ✅ **Zero Downtime Updates**: Use `--update` flag to update without downtime
### Updating a Deployment
```bash
# Make changes to your app
# Rebuild
npm run build
# Update deployment
orama deploy static ./dist --name my-react-app --update
# Version increments automatically (1 → 2)
```
---
## Deploying Next.js Applications
Deploy Next.js apps with full SSR (Server-Side Rendering) support.
### Next.js with SSR
```bash
# 1. Build your Next.js app
cd my-nextjs-app
npm run build
# 2. Deploy with SSR enabled
orama deploy nextjs . --name my-nextjs --ssr
# Output:
# 📦 Creating tarball from .
# ☁️ Uploading to Orama Network...
#
# ✅ Deployment successful!
#
# Name: my-nextjs
# Type: nextjs
# Status: active
# Version: 1
# Port: 10100
#
# URLs:
# • https://my-nextjs.orama.network
#
# ⚠️ Note: SSR deployment may take a minute to start. Check status with: orama deployments get my-nextjs
```
### What Happens Behind the Scenes
1. **Tarball Upload**: Your `.next` build directory, `package.json`, and `public` are uploaded
2. **Home Node Assignment**: A node is chosen to host your app based on capacity
3. **Port Allocation**: A unique port (10100-19999) is assigned
4. **Systemd Service**: A systemd service is created to run `node server.js`
5. **Health Checks**: Gateway monitors your app every 30 seconds
6. **Reverse Proxy**: Gateway proxies requests from your domain to the local port
### Static Next.js Export (No SSR)
If you export Next.js to static HTML:
```bash
# next.config.js
module.exports = {
output: 'export'
}
# Build and deploy as static
npm run build
orama deploy static ./out --name my-nextjs-static
```
---
## Deploying Go Backends
Deploy compiled Go binaries for high-performance APIs.
### Go REST API Example
```bash
# 1. Build your Go binary for Linux (if on Mac/Windows)
cd my-go-api
GOOS=linux GOARCH=amd64 go build -o api main.go
# 2. Deploy the binary
orama deploy go ./api --name my-api
# Output:
# 📦 Creating tarball from ./api...
# ☁️ Uploading to Orama Network...
#
# ✅ Deployment successful!
#
# Name: my-api
# Type: go
# Status: active
# Version: 1
# Port: 10101
#
# URLs:
# • https://my-api.orama.network
```
### Example Go API Code
```go
// main.go
package main
import (
"encoding/json"
"log"
"net/http"
"os"
)
func main() {
port := os.Getenv("PORT")
if port == "" {
port = "8080"
}
http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
json.NewEncoder(w).Encode(map[string]string{"status": "healthy"})
})
http.HandleFunc("/api/users", func(w http.ResponseWriter, r *http.Request) {
users := []map[string]interface{}{
{"id": 1, "name": "Alice"},
{"id": 2, "name": "Bob"},
}
json.NewEncoder(w).Encode(users)
})
log.Printf("Starting server on port %s", port)
log.Fatal(http.ListenAndServe(":"+port, nil))
}
```
### Important Notes
- **Environment Variables**: The `PORT` environment variable is automatically set to your allocated port
- **Health Endpoint**: Recommended to implement `/health` for monitoring
- **Binary Requirements**: Must be Linux-compatible (GOOS=linux GOARCH=amd64)
- **Systemd Managed**: Runs as a systemd service with auto-restart on failure
---
## Deploying Node.js Backends
Deploy Node.js/Express/TypeScript backends.
### Express API Example
```bash
# 1. Build your Node.js app (if using TypeScript)
cd my-node-api
npm run build
# 2. Deploy (must include node_modules or use a bundler)
orama deploy nodejs ./dist --name my-node-api
# Output:
# 📦 Creating tarball from ./dist...
# ☁️ Uploading to Orama Network...
#
# ✅ Deployment successful!
#
# Name: my-node-api
# Type: nodejs
# Status: active
# Version: 1
# Port: 10102
#
# URLs:
# • https://my-node-api.orama.network
```
### Example Node.js API
```javascript
// server.js
const express = require('express');
const app = express();
const port = process.env.PORT || 8080;
app.get('/health', (req, res) => {
res.json({ status: 'healthy' });
});
app.get('/api/data', (req, res) => {
res.json({ message: 'Hello from Orama Network!' });
});
app.listen(port, () => {
console.log(`Server running on port ${port}`);
});
```
---
## Managing SQLite Databases
Each namespace gets its own isolated SQLite databases.
### Creating a Database
```bash
# Create a new database
orama db create my-database
# Output:
# ✅ Database created: my-database
# Home Node: node-abc123
# File Path: /home/debros/.orama/data/sqlite/your-namespace/my-database.db
```
### Executing Queries
```bash
# Create a table
orama db query my-database "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)"
# Insert data
orama db query my-database "INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com')"
# Query data
orama db query my-database "SELECT * FROM users"
# Output:
# 📊 Query Result
# Rows: 1
#
# id | name | email
# ----------------+-----------------+-------------------------
# 1 | Alice | alice@example.com
```
### Listing Databases
```bash
orama db list
# Output:
# NAME SIZE HOME NODE CREATED
# my-database 12.3 KB node-abc123 2024-01-22 10:30
# prod-database 1.2 MB node-abc123 2024-01-20 09:15
#
# Total: 2
```
### Backing Up to IPFS
```bash
# Create a backup
orama db backup my-database
# Output:
# ✅ Backup created
# CID: QmYxxx...
# Size: 12.3 KB
# List backups
orama db backups my-database
# Output:
# VERSION CID SIZE DATE
# 1 QmYxxx... 12.3 KB 2024-01-22 10:45
# 2 QmZxxx... 15.1 KB 2024-01-22 14:20
```
### Database Features
- ✅ **WAL Mode**: Write-Ahead Logging for better concurrency
- ✅ **Namespace Isolation**: Complete separation between namespaces
- ✅ **Automatic Backups**: Scheduled backups to IPFS every 6 hours
- ✅ **ACID Transactions**: Full SQLite transactional support
- ✅ **Concurrent Reads**: Multiple readers can query simultaneously
---
## How Domains Work
### Domain Assignment
When you deploy an application, it automatically gets a domain:
```
Format: {deployment-name}.orama.network
Example: my-react-app.orama.network
```
### Node-Specific Domains (Optional)
For direct access to a specific node:
```
Format: {deployment-name}.{node-id}.orama.network
Example: my-react-app.node-7prvNa.orama.network
```
### DNS Resolution Flow
1. **Client**: Browser requests `my-react-app.orama.network`
2. **DNS**: CoreDNS server queries RQLite for DNS record
3. **Record**: Returns IP address of a gateway node
4. **Gateway**: Receives request with `Host: my-react-app.orama.network` header
5. **Routing**: Domain routing middleware looks up deployment by domain
6. **Response**:
- **Static**: Serves content from IPFS
- **Dynamic**: Reverse proxies to the app's local port
### Custom Domains (Future Feature)
Support for custom domains (e.g., `www.myapp.com`) with TXT record verification.
---
## Full-Stack Application Example
Deploy a complete full-stack application with React frontend, Go backend, and SQLite database.
### Architecture
```
┌─────────────────────────────────────────────┐
│ React Frontend (Static) │
│ Domain: myapp.orama.network │
│ Deployed to IPFS │
└─────────────────┬───────────────────────────┘
│
│ API Calls
▼
┌─────────────────────────────────────────────┐
│ Go Backend (Dynamic) │
│ Domain: myapp-api.orama.network │
│ Port: 10100 │
│ Systemd Service │
└─────────────────┬───────────────────────────┘
│
│ SQL Queries
▼
┌─────────────────────────────────────────────┐
│ SQLite Database │
│ Name: myapp-db │
│ File: ~/.orama/data/sqlite/ns/myapp-db.db│
└─────────────────────────────────────────────┘
```
### Step 1: Create the Database
```bash
# Create database
orama db create myapp-db
# Create schema
orama db query myapp-db "CREATE TABLE users (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
email TEXT UNIQUE NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)"
# Insert test data
orama db query myapp-db "INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com')"
```
### Step 2: Deploy Go Backend
**Backend Code** (`main.go`):
```go
package main
import (
"database/sql"
"encoding/json"
"log"
"net/http"
"os"
_ "github.com/mattn/go-sqlite3"
)
type User struct {
ID int `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
CreatedAt string `json:"created_at"`
}
var db *sql.DB
func main() {
// DATABASE_NAME env var is automatically set by Orama
dbPath := os.Getenv("DATABASE_PATH")
if dbPath == "" {
dbPath = "/home/debros/.orama/data/sqlite/" + os.Getenv("NAMESPACE") + "/myapp-db.db"
}
var err error
db, err = sql.Open("sqlite3", dbPath)
if err != nil {
log.Fatal(err)
}
defer db.Close()
port := os.Getenv("PORT")
if port == "" {
port = "8080"
}
// CORS middleware
http.HandleFunc("/", corsMiddleware(routes))
log.Printf("Starting server on port %s", port)
log.Fatal(http.ListenAndServe(":"+port, nil))
}
func routes(w http.ResponseWriter, r *http.Request) {
switch r.URL.Path {
case "/health":
json.NewEncoder(w).Encode(map[string]string{"status": "healthy"})
case "/api/users":
if r.Method == "GET" {
getUsers(w, r)
} else if r.Method == "POST" {
createUser(w, r)
}
default:
http.NotFound(w, r)
}
}
func getUsers(w http.ResponseWriter, r *http.Request) {
rows, err := db.Query("SELECT id, name, email, created_at FROM users ORDER BY id")
if err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
defer rows.Close()
var users []User
for rows.Next() {
var u User
rows.Scan(&u.ID, &u.Name, &u.Email, &u.CreatedAt)
users = append(users, u)
}
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(users)
}
func createUser(w http.ResponseWriter, r *http.Request) {
var u User
if err := json.NewDecoder(r.Body).Decode(&u); err != nil {
http.Error(w, err.Error(), http.StatusBadRequest)
return
}
result, err := db.Exec("INSERT INTO users (name, email) VALUES (?, ?)", u.Name, u.Email)
if err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
id, _ := result.LastInsertId()
u.ID = int(id)
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusCreated)
json.NewEncoder(w).Encode(u)
}
func corsMiddleware(next http.HandlerFunc) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Access-Control-Allow-Origin", "*")
w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
if r.Method == "OPTIONS" {
w.WriteHeader(http.StatusOK)
return
}
next(w, r)
}
}
```
**Deploy Backend**:
```bash
# Build for Linux
GOOS=linux GOARCH=amd64 go build -o api main.go
# Deploy
orama deploy go ./api --name myapp-api
```
### Step 3: Deploy React Frontend
**Frontend Code** (`src/App.jsx`):
```jsx
import { useEffect, useState } from 'react';
function App() {
const [users, setUsers] = useState([]);
const [name, setName] = useState('');
const [email, setEmail] = useState('');
const API_URL = 'https://myapp-api.orama.network';
useEffect(() => {
fetchUsers();
}, []);
const fetchUsers = async () => {
const response = await fetch(`${API_URL}/api/users`);
const data = await response.json();
setUsers(data);
};
const addUser = async (e) => {
e.preventDefault();
await fetch(`${API_URL}/api/users`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ name, email }),
});
setName('');
setEmail('');
fetchUsers();
};
return (
<div>
<h1>Orama Network Full-Stack App</h1>
<h2>Add User</h2>
<form onSubmit={addUser}>
<input
value={name}
onChange={(e) => setName(e.target.value)}
placeholder="Name"
required
/>
<input
value={email}
onChange={(e) => setEmail(e.target.value)}
placeholder="Email"
type="email"
required
/>
<button type="submit">Add User</button>
</form>
<h2>Users</h2>
<ul>
{users.map((user) => (
<li key={user.id}>
{user.name} - {user.email}
</li>
))}
</ul>
</div>
);
}
export default App;
```
**Deploy Frontend**:
```bash
# Build
npm run build
# Deploy
orama deploy static ./dist --name myapp
```
### Step 4: Access Your App
Open your browser to:
- **Frontend**: `https://myapp.orama.network`
- **Backend API**: `https://myapp-api.orama.network/api/users`
### Full-Stack Summary
✅ **Frontend**: React app served from IPFS
✅ **Backend**: Go API running on allocated port
✅ **Database**: SQLite database with ACID transactions
✅ **Domains**: Automatic DNS for both services
✅ **Isolated**: All resources namespaced and secure
---
## Managing Deployments
### List All Deployments
```bash
orama deployments list
# Output:
# NAME TYPE STATUS VERSION CREATED
# my-react-app static active 1 2024-01-22 10:30
# myapp-api go active 1 2024-01-22 10:45
# my-nextjs nextjs active 2 2024-01-22 11:00
#
# Total: 3
```
### Get Deployment Details
```bash
orama deployments get my-react-app
# Output:
# Deployment: my-react-app
#
# ID: dep-abc123
# Type: static
# Status: active
# Version: 1
# Namespace: your-namespace
# Content CID: QmXxxx...
# Memory Limit: 256 MB
# CPU Limit: 50%
# Restart Policy: always
#
# URLs:
# • https://my-react-app.orama.network
#
# Created: 2024-01-22T10:30:00Z
# Updated: 2024-01-22T10:30:00Z
```
### View Logs
```bash
# View last 100 lines
orama deployments logs my-nextjs
# Follow logs in real-time
orama deployments logs my-nextjs --follow
```
### Rollback to Previous Version
```bash
# Rollback to version 1
orama deployments rollback my-nextjs --version 1
# Output:
# ⚠️ Rolling back 'my-nextjs' to version 1. Continue? (y/N): y
#
# ✅ Rollback successful!
#
# Deployment: my-nextjs
# Current Version: 1
# Rolled Back From: 2
# Rolled Back To: 1
# Status: active
```
### Delete Deployment
```bash
orama deployments delete my-old-app
# Output:
# ⚠️ Are you sure you want to delete deployment 'my-old-app'? (y/N): y
#
# ✅ Deployment 'my-old-app' deleted successfully
```
---
## Troubleshooting
### Deployment Issues
**Problem**: Deployment status is "failed"
```bash
# Check deployment details
orama deployments get my-app
# View logs for errors
orama deployments logs my-app
# Common issues:
# - Binary not compiled for Linux (GOOS=linux GOARCH=amd64)
# - Missing dependencies (node_modules not included)
# - Port already in use (shouldn't happen, but check logs)
# - Health check failing (ensure /health endpoint exists)
```
**Problem**: Can't access deployment URL
```bash
# 1. Check deployment status
orama deployments get my-app
# 2. Verify DNS (may take up to 10 seconds to propagate)
dig my-app.orama.network
# 3. For local development, add to /etc/hosts
echo "127.0.0.1 my-app.orama.network" | sudo tee -a /etc/hosts
# 4. Test with Host header
curl -H "Host: my-app.orama.network" http://localhost:6001/
```
### Database Issues
**Problem**: Database not found
```bash
# List all databases
orama db list
# Ensure database name matches exactly (case-sensitive)
# Databases are namespace-isolated
```
**Problem**: SQL query fails
```bash
# Check table exists
orama db query my-db "SELECT name FROM sqlite_master WHERE type='table'"
# Check syntax
orama db query my-db ".schema users"
```
### Authentication Issues
```bash
# Re-authenticate
orama auth logout
orama auth login
# Check token validity
orama auth status
```
### Need Help?
- **Documentation**: Check `/docs` directory
- **Logs**: Gateway logs at `~/.orama/logs/gateway.log`
- **Issues**: Report bugs at GitHub repository
- **Community**: Join our Discord/Telegram
---
## Best Practices
### Security
1. **Never commit sensitive data**: Use environment variables for secrets
2. **Validate inputs**: Always sanitize user input in your backend
3. **HTTPS only**: All deployments automatically use HTTPS in production
4. **CORS**: Configure CORS appropriately for your API
### Performance
1. **Optimize builds**: Minimize bundle sizes (React, Next.js)
2. **Use caching**: Leverage browser caching for static assets
3. **Database indexes**: Add indexes to frequently queried columns
4. **Health checks**: Implement `/health` endpoint for monitoring
### Deployment Workflow
1. **Test locally first**: Ensure your app works before deploying
2. **Use version control**: Track changes in Git
3. **Incremental updates**: Use `--update` flag instead of delete + redeploy
4. **Backup databases**: Regular backups via `orama db backup`
5. **Monitor logs**: Check logs after deployment for errors
---
## Next Steps
- **Explore the API**: See `/docs/GATEWAY_API.md` for HTTP API details
- **Advanced Features**: Custom domains, load balancing, autoscaling (coming soon)
- **Production Deployment**: Install nodes with `orama install` for production clusters
- **Client SDK**: Use the Go/JS SDK for programmatic deployments
---
**Orama Network** - Decentralized Application Platform
Deploy anywhere. Access everywhere. Own everything.

734
docs/GATEWAY_API.md
View File

@ -1,734 +0,0 @@
# Gateway API Documentation
## Overview
The Orama Network Gateway provides a unified HTTP/HTTPS API for all network services. It handles authentication, routing, and service coordination.
**Base URL:** `https://api.orama.network` (production) or `http://localhost:6001` (development)
## Authentication
All API requests (except `/health` and `/v1/auth/*`) require authentication.
### Authentication Methods
1. **API Key** (Recommended for server-to-server)
2. **JWT Token** (Recommended for user sessions)
3. **Wallet Signature** (For blockchain integration)
### Using API Keys
Include your API key in the `Authorization` header:
```bash
curl -H "Authorization: Bearer your-api-key-here" \
https://api.orama.network/v1/status
```
Or in the `X-API-Key` header:
```bash
curl -H "X-API-Key: your-api-key-here" \
https://api.orama.network/v1/status
```
### Using JWT Tokens
```bash
curl -H "Authorization: Bearer your-jwt-token-here" \
https://api.orama.network/v1/status
```
## Base Endpoints
### Health Check
```http
GET /health
```
**Response:**
```json
{
"status": "ok",
"timestamp": "2024-01-20T10:30:00Z"
}
```
### Status
```http
GET /v1/status
```
**Response:**
```json
{
"version": "0.80.0",
"uptime": "24h30m15s",
"services": {
"rqlite": "healthy",
"ipfs": "healthy",
"olric": "healthy"
}
}
```
### Version
```http
GET /v1/version
```
**Response:**
```json
{
"version": "0.80.0",
"commit": "abc123...",
"built": "2024-01-20T00:00:00Z"
}
```
## Authentication API
### Get Challenge (Wallet Auth)
Generate a nonce for wallet signature.
```http
POST /v1/auth/challenge
Content-Type: application/json
{
"wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
"purpose": "login",
"namespace": "default"
}
```
**Response:**
```json
{
"wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
"namespace": "default",
"nonce": "a1b2c3d4e5f6...",
"purpose": "login",
"expires_at": "2024-01-20T10:35:00Z"
}
```
### Verify Signature
Verify wallet signature and issue JWT + API key.
```http
POST /v1/auth/verify
Content-Type: application/json
{
"wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
"signature": "0x...",
"nonce": "a1b2c3d4e5f6...",
"namespace": "default"
}
```
**Response:**
```json
{
"jwt_token": "eyJhbGciOiJIUzI1NiIs...",
"refresh_token": "refresh_abc123...",
"api_key": "api_xyz789...",
"expires_in": 900,
"namespace": "default"
}
```
### Refresh Token
Refresh an expired JWT token.
```http
POST /v1/auth/refresh
Content-Type: application/json
{
"refresh_token": "refresh_abc123..."
}
```
**Response:**
```json
{
"jwt_token": "eyJhbGciOiJIUzI1NiIs...",
"expires_in": 900
}
```
### Logout
Revoke refresh tokens.
```http
POST /v1/auth/logout
Authorization: Bearer your-jwt-token
{
"all": false
}
```
**Response:**
```json
{
"message": "logged out successfully"
}
```
### Whoami
Get current authentication info.
```http
GET /v1/auth/whoami
Authorization: Bearer your-api-key
```
**Response:**
```json
{
"authenticated": true,
"method": "api_key",
"api_key": "api_xyz789...",
"namespace": "default"
}
```
## Storage API (IPFS)
### Upload File
```http
POST /v1/storage/upload
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
file: <binary data>
```
Or with JSON:
```http
POST /v1/storage/upload
Authorization: Bearer your-api-key
Content-Type: application/json
{
"data": "base64-encoded-data",
"filename": "document.pdf",
"pin": true,
"encrypt": false
}
```
**Response:**
```json
{
"cid": "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
"size": 1024,
"filename": "document.pdf"
}
```
### Get File
```http
GET /v1/storage/get/:cid
Authorization: Bearer your-api-key
```
**Response:** Binary file data or JSON (if `Accept: application/json`)
### Pin File
```http
POST /v1/storage/pin
Authorization: Bearer your-api-key
Content-Type: application/json
{
"cid": "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
"replication_factor": 3
}
```
**Response:**
```json
{
"cid": "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
"status": "pinned"
}
```
### Unpin File
```http
DELETE /v1/storage/unpin/:cid
Authorization: Bearer your-api-key
```
**Response:**
```json
{
"message": "unpinned successfully"
}
```
### Get Pin Status
```http
GET /v1/storage/status/:cid
Authorization: Bearer your-api-key
```
**Response:**
```json
{
"cid": "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
"status": "pinned",
"replicas": 3,
"peers": ["12D3KooW...", "12D3KooW..."]
}
```
## Cache API (Olric)
### Set Value
```http
PUT /v1/cache/put
Authorization: Bearer your-api-key
Content-Type: application/json
{
"key": "user:123",
"value": {"name": "Alice", "email": "alice@example.com"},
"ttl": 300
}
```
**Response:**
```json
{
"message": "value set successfully"
}
```
### Get Value
```http
GET /v1/cache/get?key=user:123
Authorization: Bearer your-api-key
```
**Response:**
```json
{
"key": "user:123",
"value": {"name": "Alice", "email": "alice@example.com"}
}
```
### Get Multiple Values
```http
POST /v1/cache/mget
Authorization: Bearer your-api-key
Content-Type: application/json
{
"keys": ["user:1", "user:2", "user:3"]
}
```
**Response:**
```json
{
"results": {
"user:1": {"name": "Alice"},
"user:2": {"name": "Bob"},
"user:3": null
}
}
```
### Delete Value
```http
DELETE /v1/cache/delete?key=user:123
Authorization: Bearer your-api-key
```
**Response:**
```json
{
"message": "deleted successfully"
}
```
### Scan Keys
```http
GET /v1/cache/scan?pattern=user:*&limit=100
Authorization: Bearer your-api-key
```
**Response:**
```json
{
"keys": ["user:1", "user:2", "user:3"],
"count": 3
}
```
## Database API (RQLite)
### Execute SQL
```http
POST /v1/rqlite/exec
Authorization: Bearer your-api-key
Content-Type: application/json
{
"sql": "INSERT INTO users (name, email) VALUES (?, ?)",
"args": ["Alice", "alice@example.com"]
}
```
**Response:**
```json
{
"last_insert_id": 123,
"rows_affected": 1
}
```
### Query SQL
```http
POST /v1/rqlite/query
Authorization: Bearer your-api-key
Content-Type: application/json
{
"sql": "SELECT * FROM users WHERE id = ?",
"args": [123]
}
```
**Response:**
```json
{
"columns": ["id", "name", "email"],
"rows": [
[123, "Alice", "alice@example.com"]
]
}
```
### Get Schema
```http
GET /v1/rqlite/schema
Authorization: Bearer your-api-key
```
**Response:**
```json
{
"tables": [
{
"name": "users",
"schema": "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)"
}
]
}
```
## Pub/Sub API
### Publish Message
```http
POST /v1/pubsub/publish
Authorization: Bearer your-api-key
Content-Type: application/json
{
"topic": "chat",
"data": "SGVsbG8sIFdvcmxkIQ==",
"namespace": "default"
}
```
**Response:**
```json
{
"message": "published successfully"
}
```
### List Topics
```http
GET /v1/pubsub/topics
Authorization: Bearer your-api-key
```
**Response:**
```json
{
"topics": ["chat", "notifications", "events"]
}
```
### Subscribe (WebSocket)
```http
GET /v1/pubsub/ws?topic=chat
Authorization: Bearer your-api-key
Upgrade: websocket
```
**WebSocket Messages:**
Incoming (from server):
```json
{
"type": "message",
"topic": "chat",
"data": "SGVsbG8sIFdvcmxkIQ==",
"timestamp": "2024-01-20T10:30:00Z"
}
```
Outgoing (to server):
```json
{
"type": "publish",
"topic": "chat",
"data": "SGVsbG8sIFdvcmxkIQ=="
}
```
### Presence
```http
GET /v1/pubsub/presence?topic=chat
Authorization: Bearer your-api-key
```
**Response:**
```json
{
"topic": "chat",
"members": [
{"id": "user-123", "joined_at": "2024-01-20T10:00:00Z"},
{"id": "user-456", "joined_at": "2024-01-20T10:15:00Z"}
]
}
```
## Serverless API (WASM)
### Deploy Function
```http
POST /v1/functions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
name: hello-world
namespace: default
description: Hello world function
wasm: <binary WASM file>
memory_limit: 64
timeout: 30
```
**Response:**
```json
{
"id": "fn_abc123",
"name": "hello-world",
"namespace": "default",
"wasm_cid": "QmXxx...",
"version": 1,
"created_at": "2024-01-20T10:30:00Z"
}
```
### Invoke Function
```http
POST /v1/functions/hello-world/invoke
Authorization: Bearer your-api-key
Content-Type: application/json
{
"name": "Alice"
}
```
**Response:**
```json
{
"result": "Hello, Alice!",
"execution_time_ms": 15,
"memory_used_mb": 2.5
}
```
### List Functions
```http
GET /v1/functions?namespace=default
Authorization: Bearer your-api-key
```
**Response:**
```json
{
"functions": [
{
"name": "hello-world",
"description": "Hello world function",
"version": 1,
"created_at": "2024-01-20T10:30:00Z"
}
]
}
```
### Delete Function
```http
DELETE /v1/functions/hello-world?namespace=default
Authorization: Bearer your-api-key
```
**Response:**
```json
{
"message": "function deleted successfully"
}
```
### Get Function Logs
```http
GET /v1/functions/hello-world/logs?limit=100
Authorization: Bearer your-api-key
```
**Response:**
```json
{
"logs": [
{
"timestamp": "2024-01-20T10:30:00Z",
"level": "info",
"message": "Function invoked",
"invocation_id": "inv_xyz789"
}
]
}
```
## Error Responses
All errors follow a consistent format:
```json
{
"code": "NOT_FOUND",
"message": "user with ID '123' not found",
"details": {
"resource": "user",
"id": "123"
},
"trace_id": "trace-abc123"
}
```
### Common Error Codes
| Code | HTTP Status | Description |
|------|-------------|-------------|
| `VALIDATION_ERROR` | 400 | Invalid input |
| `UNAUTHORIZED` | 401 | Authentication required |
| `FORBIDDEN` | 403 | Permission denied |
| `NOT_FOUND` | 404 | Resource not found |
| `CONFLICT` | 409 | Resource already exists |
| `TIMEOUT` | 408 | Operation timeout |
| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests |
| `SERVICE_UNAVAILABLE` | 503 | Service unavailable |
| `INTERNAL` | 500 | Internal server error |
## Rate Limiting
The API implements rate limiting per API key:
- **Default:** 100 requests per minute
- **Burst:** 200 requests
Rate limit headers:
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1611144000
```
When rate limited:
```json
{
"code": "RATE_LIMIT_EXCEEDED",
"message": "rate limit exceeded",
"details": {
"limit": 100,
"retry_after": 60
}
}
```
## Pagination
List endpoints support pagination:
```http
GET /v1/functions?limit=10&offset=20
```
Response includes pagination metadata:
```json
{
"data": [...],
"pagination": {
"total": 100,
"limit": 10,
"offset": 20,
"has_more": true
}
}
```
## Webhooks (Future)
Coming soon: webhook support for event notifications.
## Support
- API Issues: https://github.com/DeBrosOfficial/network/issues
- OpenAPI Spec: `openapi/gateway.yaml`
- SDK Documentation: `docs/CLIENT_SDK.md`

476
docs/SECURITY_DEPLOYMENT_GUIDE.md
View File

@ -1,476 +0,0 @@
# Orama Network - Security Deployment Guide
**Date:** January 18, 2026
**Status:** Production-Ready
**Audit Completed By:** Claude Code Security Audit
---
## Executive Summary
This document outlines the security hardening measures applied to the 4-node Orama Network production cluster. All critical vulnerabilities identified in the security audit have been addressed.
**Security Status:** ✅ SECURED FOR PRODUCTION
---
## Server Inventory
| Server ID | IP Address | Domain | OS | Role |
|-----------|------------|--------|-----|------|
| VPS 1 | 51.83.128.181 | node-kv4la8.debros.network | Ubuntu 22.04 | Gateway + Cluster Node |
| VPS 2 | 194.61.28.7 | node-7prvNa.debros.network | Ubuntu 24.04 | Gateway + Cluster Node |
| VPS 3 | 83.171.248.66 | node-xn23dq.debros.network | Ubuntu 24.04 | Gateway + Cluster Node |
| VPS 4 | 62.72.44.87 | node-nns4n5.debros.network | Ubuntu 24.04 | Gateway + Cluster Node |
---
## Services Running on Each Server
| Service | Port(s) | Purpose | Public Access |
|---------|---------|---------|---------------|
| **orama-node** | 80, 443, 7001 | API Gateway | Yes (80, 443 only) |
| **rqlited** | 5001, 7002 | Distributed SQLite DB | Cluster only |
| **ipfs** | 4101, 4501, 8080 | Content-addressed storage | Cluster only |
| **ipfs-cluster** | 9094, 9098 | IPFS cluster management | Cluster only |
| **olric-server** | 3320, 3322 | Distributed cache | Cluster only |
| **anon** (Anyone proxy) | 9001, 9050, 9051 | Anonymity proxy | Cluster only |
| **libp2p** | 4001 | P2P networking | Yes (public P2P) |
| **SSH** | 22 | Remote access | Yes |
---
## Security Measures Implemented
### 1. Firewall Configuration (UFW)
**Status:** ✅ Enabled on all 4 servers
#### Public Ports (Open to Internet)
- **22/tcp** - SSH (with hardening)
- **80/tcp** - HTTP (redirects to HTTPS)
- **443/tcp** - HTTPS (Let's Encrypt production certificates)
- **4001/tcp** - libp2p swarm (P2P networking)
#### Cluster-Only Ports (Restricted to 4 Server IPs)
All the following ports are ONLY accessible from the 4 cluster IPs:
- **5001/tcp** - rqlite HTTP API
- **7001/tcp** - SNI Gateway
- **7002/tcp** - rqlite Raft consensus
- **9094/tcp** - IPFS Cluster API
- **9098/tcp** - IPFS Cluster communication
- **3322/tcp** - Olric distributed cache
- **4101/tcp** - IPFS swarm (cluster internal)
#### Firewall Rules Example
```bash
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp comment "SSH"
sudo ufw allow 80/tcp comment "HTTP"
sudo ufw allow 443/tcp comment "HTTPS"
sudo ufw allow 4001/tcp comment "libp2p swarm"
# Cluster-only access for sensitive services
sudo ufw allow from 51.83.128.181 to any port 5001 proto tcp
sudo ufw allow from 194.61.28.7 to any port 5001 proto tcp
sudo ufw allow from 83.171.248.66 to any port 5001 proto tcp
sudo ufw allow from 62.72.44.87 to any port 5001 proto tcp
# (repeat for ports 7001, 7002, 9094, 9098, 3322, 4101)
sudo ufw enable
```
### 2. SSH Hardening
**Location:** `/etc/ssh/sshd_config.d/99-hardening.conf`
**Configuration:**
```bash
PermitRootLogin yes # Root login allowed with SSH keys
PasswordAuthentication yes # Password auth enabled (you have keys configured)
PubkeyAuthentication yes # SSH key authentication enabled
PermitEmptyPasswords no # No empty passwords
X11Forwarding no # X11 disabled for security
MaxAuthTries 3 # Max 3 login attempts
ClientAliveInterval 300 # Keep-alive every 5 minutes
ClientAliveCountMax 2 # Disconnect after 2 failed keep-alives
```
**Your SSH Keys Added:**
- ✅ `ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPcGZPX2iHXWO8tuyyDkHPS5eByPOktkw3+ugcw79yQO`
- ✅ `ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDgCWmycaBN3aAZJcM2w4+Xi2zrTwN78W8oAiQywvMEkubqNNWHF6I3...`
Both keys are installed on all 4 servers in:
- VPS 1: `/home/ubuntu/.ssh/authorized_keys`
- VPS 2, 3, 4: `/root/.ssh/authorized_keys`
### 3. Fail2ban Protection
**Status:** ✅ Installed and running on all 4 servers
**Purpose:** Automatically bans IPs after failed SSH login attempts
**Check Status:**
```bash
sudo systemctl status fail2ban
```
### 4. Security Updates
**Status:** ✅ All security updates applied (as of Jan 18, 2026)
**Update Command:**
```bash
sudo apt update && sudo apt upgrade -y
```
### 5. Let's Encrypt TLS Certificates
**Status:** ✅ Production certificates (NOT staging)
**Configuration:**
- **Provider:** Let's Encrypt (ACME v2 Production)
- **Auto-renewal:** Enabled via autocert
- **Cache Directory:** `/home/debros/.orama/tls-cache/`
- **Domains:**
- node-kv4la8.debros.network (VPS 1)
- node-7prvNa.debros.network (VPS 2)
- node-xn23dq.debros.network (VPS 3)
- node-nns4n5.debros.network (VPS 4)
**Certificate Files:**
- Account key: `/home/debros/.orama/tls-cache/acme_account+key`
- Certificates auto-managed by autocert
**Verification:**
```bash
curl -I https://node-kv4la8.debros.network
# Should return valid SSL certificate
```
---
## Cluster Configuration
### RQLite Cluster
**Nodes:**
- 51.83.128.181:7002 (Leader)
- 194.61.28.7:7002
- 83.171.248.66:7002
- 62.72.44.87:7002
**Test Cluster Health:**
```bash
ssh ubuntu@51.83.128.181
curl -s http://localhost:5001/status | jq '.store.nodes'
```
**Expected Output:**
```json
[
{"id":"194.61.28.7:7002","addr":"194.61.28.7:7002","suffrage":"Voter"},
{"id":"51.83.128.181:7002","addr":"51.83.128.181:7002","suffrage":"Voter"},
{"id":"62.72.44.87:7002","addr":"62.72.44.87:7002","suffrage":"Voter"},
{"id":"83.171.248.66:7002","addr":"83.171.248.66:7002","suffrage":"Voter"}
]
```
### IPFS Cluster
**Test Cluster Health:**
```bash
ssh ubuntu@51.83.128.181
curl -s http://localhost:9094/id | jq '.cluster_peers'
```
**Expected:** All 4 peer IDs listed
### Olric Cache Cluster
**Port:** 3320 (localhost), 3322 (cluster communication)
**Test:**
```bash
ssh ubuntu@51.83.128.181
ss -tulpn | grep olric
```
---
## Access Credentials
### SSH Access
**VPS 1:**
```bash
ssh ubuntu@51.83.128.181
# OR using your SSH key:
ssh -i ~/.ssh/ssh-sotiris/id_ed25519 ubuntu@51.83.128.181
```
**VPS 2, 3, 4:**
```bash
ssh root@194.61.28.7
ssh root@83.171.248.66
ssh root@62.72.44.87
```
**Important:** Password authentication is still enabled, but your SSH keys are configured for passwordless access.
---
## Testing & Verification
### 1. Test External Port Access (From Your Machine)
```bash
# These should be BLOCKED (timeout or connection refused):
nc -zv 51.83.128.181 5001 # rqlite API - should be blocked
nc -zv 51.83.128.181 7002 # rqlite Raft - should be blocked
nc -zv 51.83.128.181 9094 # IPFS cluster - should be blocked
# These should be OPEN:
nc -zv 51.83.128.181 22 # SSH - should succeed
nc -zv 51.83.128.181 80 # HTTP - should succeed
nc -zv 51.83.128.181 443 # HTTPS - should succeed
nc -zv 51.83.128.181 4001 # libp2p - should succeed
```
### 2. Test Domain Access
```bash
curl -I https://node-kv4la8.debros.network
curl -I https://node-7prvNa.debros.network
curl -I https://node-xn23dq.debros.network
curl -I https://node-nns4n5.debros.network
```
All should return `HTTP/1.1 200 OK` or similar with valid SSL certificates.
### 3. Test Cluster Communication (From VPS 1)
```bash
ssh ubuntu@51.83.128.181
# Test rqlite cluster
curl -s http://localhost:5001/status | jq -r '.store.nodes[].id'
# Test IPFS cluster
curl -s http://localhost:9094/id | jq -r '.cluster_peers[]'
# Check all services running
ps aux | grep -E "(orama-node|rqlited|ipfs|olric)" | grep -v grep
```
---
## Maintenance & Operations
### Firewall Management
**View current rules:**
```bash
sudo ufw status numbered
```
**Add a new allowed IP for cluster services:**
```bash
sudo ufw allow from NEW_IP_ADDRESS to any port 5001 proto tcp
sudo ufw allow from NEW_IP_ADDRESS to any port 7002 proto tcp
# etc.
```
**Delete a rule:**
```bash
sudo ufw status numbered # Get rule number
sudo ufw delete [NUMBER]
```
### SSH Management
**Test SSH config without applying:**
```bash
sudo sshd -t
```
**Reload SSH after config changes:**
```bash
sudo systemctl reload ssh
```
**View SSH login attempts:**
```bash
sudo journalctl -u ssh | tail -50
```
### Fail2ban Management
**Check banned IPs:**
```bash
sudo fail2ban-client status sshd
```
**Unban an IP:**
```bash
sudo fail2ban-client set sshd unbanip IP_ADDRESS
```
### Security Updates
**Check for updates:**
```bash
apt list --upgradable
```
**Apply updates:**
```bash
sudo apt update && sudo apt upgrade -y
```
**Reboot if kernel updated:**
```bash
sudo reboot
```
---
## Security Improvements Completed
### Before Security Audit:
- ❌ No firewall enabled
- ❌ rqlite database exposed to internet (port 5001, 7002)
- ❌ IPFS cluster management exposed (port 9094, 9098)
- ❌ Olric cache exposed (port 3322)
- ❌ Root login enabled without restrictions (VPS 2, 3, 4)
- ❌ No fail2ban on 3 out of 4 servers
- ❌ 19-39 security updates pending
### After Security Hardening:
- ✅ UFW firewall enabled on all servers
- ✅ Sensitive ports restricted to cluster IPs only
- ✅ SSH hardened with key authentication
- ✅ Fail2ban protecting all servers
- ✅ All security updates applied
- ✅ Let's Encrypt production certificates verified
- ✅ Cluster communication tested and working
- ✅ External access verified (HTTP/HTTPS only)
---
## Recommended Next Steps (Optional)
These were not implemented per your request but are recommended for future consideration:
1. **VPN/Private Networking** - Use WireGuard or Tailscale for encrypted cluster communication instead of firewall rules
2. **Automated Security Updates** - Enable unattended-upgrades for automatic security patches
3. **Monitoring & Alerting** - Set up Prometheus/Grafana for service monitoring
4. **Regular Security Audits** - Run `lynis` or `rkhunter` monthly for security checks
---
## Important Notes
### Let's Encrypt Configuration
The Orama Network gateway uses **autocert** from Go's `golang.org/x/crypto/acme/autocert` package. The configuration is in:
**File:** `/home/debros/.orama/configs/node.yaml`
**Relevant settings:**
```yaml
http_gateway:
https:
enabled: true
domain: "node-kv4la8.debros.network"
auto_cert: true
cache_dir: "/home/debros/.orama/tls-cache"
http_port: 80
https_port: 443
email: "admin@node-kv4la8.debros.network"
```
**Important:** There is NO `letsencrypt_staging` flag set, which means it defaults to **production Let's Encrypt**. This is correct for production deployment.
### Firewall Persistence
UFW rules are persistent across reboots. The firewall will automatically start on boot.
### SSH Key Access
Both of your SSH keys are configured on all servers. You can access:
- VPS 1: `ssh -i ~/.ssh/ssh-sotiris/id_ed25519 ubuntu@51.83.128.181`
- VPS 2-4: `ssh -i ~/.ssh/ssh-sotiris/id_ed25519 root@IP_ADDRESS`
Password authentication is still enabled as a fallback, but keys are recommended.
---
## Emergency Access
If you get locked out:
1. **VPS Provider Console:** All major VPS providers offer web-based console access
2. **Password Access:** Password auth is still enabled on all servers
3. **SSH Keys:** Two keys configured for redundancy
**Disable firewall temporarily (emergency only):**
```bash
sudo ufw disable
# Fix the issue
sudo ufw enable
```
---
## Verification Checklist
Use this checklist to verify the security hardening:
- [ ] All 4 servers have UFW firewall enabled
- [ ] SSH is hardened (MaxAuthTries 3, X11Forwarding no)
- [ ] Your SSH keys work on all servers
- [ ] Fail2ban is running on all servers
- [ ] Security updates are current
- [ ] rqlite port 5001 is NOT accessible from internet
- [ ] rqlite port 7002 is NOT accessible from internet
- [ ] IPFS cluster ports 9094, 9098 are NOT accessible from internet
- [ ] Domains are accessible via HTTPS with valid certificates
- [ ] RQLite cluster shows all 4 nodes
- [ ] IPFS cluster shows all 4 peers
- [ ] All services are running (5 processes per server)
---
## Contact & Support
For issues or questions about this deployment:
- **Security Audit Date:** January 18, 2026
- **Configuration Files:** `/home/debros/.orama/configs/`
- **Firewall Rules:** `/etc/ufw/`
- **SSH Config:** `/etc/ssh/sshd_config.d/99-hardening.conf`
- **TLS Certs:** `/home/debros/.orama/tls-cache/`
---
## Changelog
### January 18, 2026 - Production Security Hardening
**Changes:**
1. Added UFW firewall rules on all 4 VPS servers
2. Restricted sensitive ports (5001, 7002, 9094, 9098, 3322, 4101) to cluster IPs only
3. Hardened SSH configuration
4. Added your 2 SSH keys to all servers
5. Installed fail2ban on VPS 1, 2, 3 (VPS 4 already had it)
6. Applied all pending security updates (23-39 packages per server)
7. Verified Let's Encrypt is using production (not staging)
8. Tested all services: rqlite, IPFS, libp2p, Olric clusters
9. Verified all 4 domains are accessible via HTTPS
**Result:** Production-ready secure deployment ✅
---
**END OF DEPLOYMENT GUIDE**

760
docs/TESTING_PLAN.md
View File

@ -1,760 +0,0 @@
# Comprehensive Testing Plan
This document outlines the complete testing strategy for the namespace isolation and custom deployment system.
## Table of Contents
1. [Unit Tests](#unit-tests)
2. [Integration Tests](#integration-tests)
3. [End-to-End Tests](#end-to-end-tests)
4. [CLI Tests](#cli-tests)
5. [Performance Tests](#performance-tests)
6. [Security Tests](#security-tests)
7. [Chaos/Failure Tests](#chaos-failure-tests)
---
## 1. Unit Tests
### 1.1 Port Allocator Tests
**File**: `pkg/deployments/port_allocator_test.go`
**Test Cases**:
- ✅ Allocate first port (should be 10100)
- ✅ Allocate sequential ports
- ✅ Find gaps in allocation
- ✅ Handle port exhaustion (all 10000 ports used)
- ✅ Concurrent allocation with race detector
- ✅ Conflict retry with exponential backoff
**Command**:
```bash
go test ./pkg/deployments -run TestPortAllocator -v
```
### 1.2 Home Node Manager Tests
**File**: `pkg/deployments/home_node_test.go`
**Test Cases**:
- ✅ Assign namespace to node with lowest load
- ✅ Reuse existing home node for namespace
- ✅ Weight calculation (deployments, ports, memory, CPU)
- ✅ Handle no nodes available
- ✅ Node failure detection and reassignment
**Command**:
```bash
go test ./pkg/deployments -run TestHomeNodeManager -v
```
### 1.3 Health Checker Tests
**File**: `pkg/deployments/health/checker_test.go` (needs to be created)
**Test Cases**:
- Check static deployment (always healthy)
- Check dynamic deployment with health endpoint
- Mark as failed after 3 consecutive failures
- Record health check history
- Parallel health checking
**Command**:
```bash
go test ./pkg/deployments/health -v
```
### 1.4 Process Manager Tests
**File**: `pkg/deployments/process/manager_test.go` (needs to be created)
**Test Cases**:
- Create systemd service file
- Start deployment process
- Stop deployment process
- Restart deployment
- Read logs from journalctl
**Command**:
```bash
go test ./pkg/deployments/process -v
```
### 1.5 Deployment Service Tests
**File**: `pkg/gateway/handlers/deployments/service_test.go` (needs to be created)
**Test Cases**:
- Create deployment
- Get deployment by ID
- List deployments for namespace
- Update deployment
- Delete deployment
- Record deployment history
**Command**:
```bash
go test ./pkg/gateway/handlers/deployments -v
```
---
## 2. Integration Tests
### 2.1 Static Deployment Integration Test
**File**: `tests/integration/static_deployment_test.go` (needs to be created)
**Setup**:
- Start test RQLite instance
- Start test IPFS node
- Start test gateway
**Test Flow**:
1. Upload static content tarball
2. Verify deployment created in database
3. Verify content uploaded to IPFS
4. Verify DNS record created
5. Test HTTP request to deployment domain
6. Verify content served correctly
**Command**:
```bash
go test ./tests/integration -run TestStaticDeployment -v
```
### 2.2 Next.js SSR Deployment Integration Test
**File**: `tests/integration/nextjs_deployment_test.go` (needs to be created)
**Test Flow**:
1. Upload Next.js build
2. Verify systemd service created
3. Verify process started
4. Wait for health check to pass
5. Test HTTP request to deployment
6. Verify SSR response
**Command**:
```bash
go test ./tests/integration -run TestNextJSDeployment -v
```
### 2.3 SQLite Database Integration Test
**File**: `tests/integration/sqlite_test.go` (needs to be created)
**Test Flow**:
1. Create SQLite database
2. Verify database file created on disk
3. Execute CREATE TABLE query
4. Execute INSERT query
5. Execute SELECT query
6. Backup database to IPFS
7. Verify backup CID recorded
**Command**:
```bash
go test ./tests/integration -run TestSQLiteDatabase -v
```
### 2.4 Custom Domain Integration Test
**File**: `tests/integration/custom_domain_test.go` (needs to be created)
**Test Flow**:
1. Add custom domain to deployment
2. Verify TXT record verification token generated
3. Mock DNS TXT record lookup
4. Verify domain
5. Verify DNS A record created
6. Test HTTP request to custom domain
**Command**:
```bash
go test ./tests/integration -run TestCustomDomain -v
```
### 2.5 Update and Rollback Integration Test
**File**: `tests/integration/update_rollback_test.go` (needs to be created)
**Test Flow**:
1. Deploy initial version
2. Update deployment with new content
3. Verify version incremented
4. Verify new content served
5. Rollback to previous version
6. Verify old content served
7. Verify history recorded correctly
**Command**:
```bash
go test ./tests/integration -run TestUpdateRollback -v
```
---
## 3. End-to-End Tests
### 3.1 Full Static Deployment E2E Test
**File**: `tests/e2e/static_deployment_test.go` (needs to be created)
**Prerequisites**:
- Running RQLite cluster
- Running IPFS cluster
- Running gateway instances
- CoreDNS configured
**Test Flow**:
1. Create test React app
2. Build app (`npm run build`)
3. Deploy via CLI: `orama deploy static ./dist --name e2e-static`
4. Wait for deployment to be active
5. Resolve deployment domain via DNS
6. Make HTTPS request to deployment
7. Verify all static assets load correctly
8. Test SPA routing (fallback to index.html)
9. Update deployment
10. Verify zero-downtime update
11. Delete deployment
12. Verify cleanup
**Command**:
```bash
go test ./tests/e2e -run TestStaticDeploymentE2E -v -timeout 10m
```
### 3.2 Full Next.js SSR Deployment E2E Test
**File**: `tests/e2e/nextjs_deployment_test.go` (needs to be created)
**Test Flow**:
1. Create test Next.js app with API routes
2. Build app (`npm run build`)
3. Deploy via CLI: `orama deploy nextjs . --name e2e-nextjs --ssr`
4. Wait for process to start and pass health check
5. Test static route
6. Test API route
7. Test SSR page
8. Update deployment with graceful restart
9. Verify health check before cutting over
10. Rollback if health check fails
11. Monitor logs during deployment
12. Delete deployment
**Command**:
```bash
go test ./tests/e2e -run TestNextJSDeploymentE2E -v -timeout 15m
```
### 3.3 Full SQLite Database E2E Test
**File**: `tests/e2e/sqlite_test.go` (needs to be created)
**Test Flow**:
1. Create database via CLI: `orama db create e2e-testdb`
2. Create schema: `orama db query e2e-testdb "CREATE TABLE ..."`
3. Insert data: `orama db query e2e-testdb "INSERT ..."`
4. Query data: `orama db query e2e-testdb "SELECT ..."`
5. Verify results match expected
6. Backup database: `orama db backup e2e-testdb`
7. List backups: `orama db backups e2e-testdb`
8. Verify backup CID in IPFS
9. Restore from backup (if implemented)
10. Verify data integrity
**Command**:
```bash
go test ./tests/e2e -run TestSQLiteDatabaseE2E -v -timeout 10m
```
### 3.4 DNS Resolution E2E Test
**File**: `tests/e2e/dns_test.go` (needs to be created)
**Test Flow**:
1. Create deployment
2. Query all 4 nameservers for deployment domain
3. Verify all return same IP
4. Add custom domain
5. Verify TXT record
6. Verify A record created
7. Query external DNS resolver
8. Verify domain resolves correctly
**Command**:
```bash
go test ./tests/e2e -run TestDNSResolutionE2E -v -timeout 5m
```
---
## 4. CLI Tests
### 4.1 Deploy Command Tests
**File**: `tests/cli/deploy_test.go` (needs to be created)
**Test Cases**:
- Deploy static site
- Deploy Next.js with --ssr flag
- Deploy Node.js backend
- Deploy Go backend
- Handle missing arguments
- Handle invalid paths
- Handle network errors gracefully
**Command**:
```bash
go test ./tests/cli -run TestDeployCommand -v
```
### 4.2 Deployments Management Tests
**File**: `tests/cli/deployments_test.go` (needs to be created)
**Test Cases**:
- List all deployments
- Get specific deployment
- Delete deployment with confirmation
- Rollback to version
- View logs with --follow
- Filter deployments by status
**Command**:
```bash
go test ./tests/cli -run TestDeploymentsCommands -v
```
### 4.3 Database Command Tests
**File**: `tests/cli/db_test.go` (needs to be created)
**Test Cases**:
- Create database
- Execute query (SELECT, INSERT, UPDATE, DELETE)
- List databases
- Backup database
- List backups
- Handle SQL syntax errors
- Handle connection errors
**Command**:
```bash
go test ./tests/cli -run TestDatabaseCommands -v
```
### 4.4 Domain Command Tests
**File**: `tests/cli/domain_test.go` (needs to be created)
**Test Cases**:
- Add custom domain
- Verify domain
- List domains
- Remove domain
- Handle verification failures
**Command**:
```bash
go test ./tests/cli -run TestDomainCommands -v
```
---
## 5. Performance Tests
### 5.1 Concurrent Deployment Test
**Objective**: Verify system handles multiple concurrent deployments
**Test**:
```bash
# Deploy 50 static sites concurrently
for i in {1..50}; do
orama deploy static ./test-site --name test-$i &
done
wait
# Verify all succeeded
orama deployments list | grep -c "active"
# Should output: 50
```
### 5.2 Port Allocation Performance Test
**Objective**: Measure port allocation speed under high contention
**Test**:
```go
func BenchmarkPortAllocation(b *testing.B) {
// Setup
db := setupTestDB()
allocator := deployments.NewPortAllocator(db, logger)
b.RunParallel(func(pb *testing.PB) {
for pb.Next() {
_, err := allocator.AllocatePort(ctx, "test-node", uuid.New().String())
if err != nil {
b.Fatal(err)
}
}
})
}
```
**Command**:
```bash
go test -bench=BenchmarkPortAllocation -benchtime=10s ./pkg/deployments
```
### 5.3 DNS Query Performance Test
**Objective**: Measure CoreDNS query latency with RQLite backend
**Test**:
```bash
# Warm up
for i in {1..1000}; do
dig @localhost test.orama.network > /dev/null
done
# Benchmark
ab -n 10000 -c 100 http://localhost:53/dns-query?name=test.orama.network
# Expected: <50ms p95 latency
```
### 5.4 Health Check Performance Test
**Objective**: Verify health checker handles 1000 deployments
**Test**:
- Create 1000 test deployments
- Start health checker
- Measure time to complete one check cycle
- Expected: <60 seconds for all 1000 checks
---
## 6. Security Tests
### 6.1 Namespace Isolation Test
**Objective**: Verify users cannot access other namespaces' resources
**Test**:
```bash
# User A deploys
export ORAMA_TOKEN="user-a-token"
orama deploy static ./site --name myapp
# User B attempts to access User A's deployment
export ORAMA_TOKEN="user-b-token"
orama deployments get myapp
# Expected: 404 Not Found or 403 Forbidden
# User B attempts to access User A's database
orama db query user-a-db "SELECT * FROM users"
# Expected: 404 Not Found or 403 Forbidden
```
### 6.2 SQL Injection Test
**Objective**: Verify SQLite handler sanitizes inputs
**Test**:
```bash
# Attempt SQL injection in database name
orama db create "test'; DROP TABLE users; --"
# Expected: Validation error
# Attempt SQL injection in query
orama db query testdb "SELECT * FROM users WHERE id = '1' OR '1'='1'"
# Expected: Query executes safely (parameterized)
```
### 6.3 Path Traversal Test
**Objective**: Verify deployment paths are sanitized
**Test**:
```bash
# Attempt path traversal in deployment name
orama deploy static ./site --name "../../etc/passwd"
# Expected: Validation error
# Attempt path traversal in SQLite database name
orama db create "../../../etc/shadow"
# Expected: Validation error
```
### 6.4 Resource Exhaustion Test
**Objective**: Verify resource limits are enforced
**Test**:
```bash
# Deploy 10001 sites (exceeds default limit)
for i in {1..10001}; do
orama deploy static ./site --name test-$i
done
# Expected: Last deployment rejected with quota error
# Create huge SQLite database
orama db query bigdb "CREATE TABLE huge (data TEXT)"
orama db query bigdb "INSERT INTO huge VALUES ('$(head -c 10G </dev/urandom | base64)')"
# Expected: Size limit enforced
```
---
## 7. Chaos/Failure Tests
### 7.1 Node Failure Test
**Objective**: Verify system handles gateway node failure
**Test**:
1. Deploy app to node A
2. Verify deployment is healthy
3. Simulate node A crash: `systemctl stop orama-gateway`
4. Wait for failure detection
5. Verify namespace migrated to node B
6. Verify deployment restored from IPFS backup
7. Verify health checks pass on node B
### 7.2 RQLite Failure Test
**Objective**: Verify graceful degradation when RQLite is unavailable
**Test**:
1. Deploy app successfully
2. Stop RQLite: `systemctl stop rqlite`
3. Attempt new deployment (should fail gracefully with error message)
4. Verify existing deployments still serve traffic (cached)
5. Restart RQLite
6. Verify new deployments work
### 7.3 IPFS Failure Test
**Objective**: Verify handling of IPFS unavailability
**Test**:
1. Deploy static site
2. Stop IPFS: `systemctl stop ipfs`
3. Attempt to serve deployment (should fail or serve from cache)
4. Attempt new deployment (should fail with clear error)
5. Restart IPFS
6. Verify recovery
### 7.4 CoreDNS Failure Test
**Objective**: Verify DNS redundancy
**Test**:
1. Stop 1 CoreDNS instance
2. Verify DNS still resolves (3 of 4 servers working)
3. Stop 2nd CoreDNS instance
4. Verify DNS still resolves (2 of 4 servers working)
5. Stop 3rd CoreDNS instance
6. Verify DNS degraded but functional (1 of 4 servers)
7. Stop all 4 CoreDNS instances
8. Verify DNS resolution fails
### 7.5 Concurrent Update Test
**Objective**: Verify race conditions are handled
**Test**:
```bash
# Update same deployment concurrently
orama deploy static ./site-v2 --name myapp --update &
orama deploy static ./site-v3 --name myapp --update &
wait
# Verify only one update succeeded
# Verify database is consistent
# Verify no partial updates
```
---
## Test Execution Plan
### Phase 1: Unit Tests (Day 1)
- Run all unit tests
- Ensure 100% pass rate
- Measure code coverage (target: >80%)
### Phase 2: Integration Tests (Days 2-3)
- Run integration tests in isolated environment
- Fix any integration issues
- Verify database state consistency
### Phase 3: E2E Tests (Days 4-5)
- Run E2E tests in staging environment
- Test with real DNS, IPFS, RQLite
- Fix any environment-specific issues
### Phase 4: Performance Tests (Day 6)
- Run load tests
- Measure latency and throughput
- Optimize bottlenecks
### Phase 5: Security Tests (Day 7)
- Run security test suite
- Fix any vulnerabilities
- Document security model
### Phase 6: Chaos Tests (Day 8)
- Run failure scenario tests
- Verify recovery procedures
- Document failure modes
### Phase 7: Production Validation (Day 9-10)
- Deploy to production with feature flag OFF
- Run smoke tests in production
- Enable feature flag for 10% of traffic
- Monitor for 24 hours
- Gradually increase to 100%
---
## Test Environment Setup
### Local Development
```bash
# Start test dependencies
docker-compose -f tests/docker-compose.test.yml up -d
# Run unit tests
make test-unit
# Run integration tests
make test-integration
# Run all tests
make test-all
```
### CI/CD Pipeline
```yaml
# .github/workflows/test.yml
name: Test
on: [push, pull_request]
jobs:
unit-tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-go@v2
- run: go test ./pkg/... -v -race -coverprofile=coverage.out
integration-tests:
runs-on: ubuntu-latest
services:
rqlite:
image: rqlite/rqlite
ipfs:
image: ipfs/go-ipfs
steps:
- uses: actions/checkout@v2
- uses: actions/setup-go@v2
- run: go test ./tests/integration/... -v -timeout 15m
e2e-tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- run: ./scripts/setup-test-env.sh
- run: go test ./tests/e2e/... -v -timeout 30m
```
---
## Success Criteria
### Unit Tests
- ✅ All tests pass
- ✅ Code coverage >80%
- ✅ No race conditions detected
### Integration Tests
- ✅ All happy path scenarios pass
- ✅ Error scenarios handled gracefully
- ✅ Database state remains consistent
### E2E Tests
- ✅ Full workflows complete successfully
- ✅ DNS resolution works across all nameservers
- ✅ Deployments accessible via HTTPS
### Performance Tests
- ✅ Port allocation: <10ms per allocation
- ✅ DNS queries: <50ms p95 latency
- ✅ Deployment creation: <30s for static, <2min for dynamic
- ✅ Health checks: Complete 1000 deployments in <60s
### Security Tests
- ✅ Namespace isolation enforced
- ✅ No SQL injection vulnerabilities
- ✅ No path traversal vulnerabilities
- ✅ Resource limits enforced
### Chaos Tests
- ✅ Node failure: Recovery within 5 minutes
- ✅ Service failure: Graceful degradation
- ✅ Concurrent updates: No race conditions
---
## Ongoing Testing
After production deployment:
1. **Synthetic Monitoring**: Create test deployments every hour and verify they work
2. **Canary Deployments**: Test new versions with 1% of traffic before full rollout
3. **Load Testing**: Weekly load tests to ensure performance doesn't degrade
4. **Security Scanning**: Automated vulnerability scans
5. **Chaos Engineering**: Monthly chaos tests in staging
---
## Test Automation Commands
```bash
# Run all tests
make test-all
# Run unit tests only
make test-unit
# Run integration tests only
make test-integration
# Run E2E tests only
make test-e2e
# Run performance tests
make test-performance
# Run security tests
make test-security
# Run chaos tests
make test-chaos
# Generate coverage report
make test-coverage
# Run tests with race detector
make test-race
```

54
pkg/cli/deployment_commands.go Normal file
View File

@ -0,0 +1,54 @@
package cli
import (
"fmt"
"os"
"github.com/DeBrosOfficial/network/pkg/cli/db"
"github.com/DeBrosOfficial/network/pkg/cli/deployments"
)
// HandleDeployCommand handles deploy commands
func HandleDeployCommand(args []string) {
deployCmd := deployments.DeployCmd
deployCmd.SetArgs(args)
if err := deployCmd.Execute(); err != nil {
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(1)
}
}
// HandleDeploymentsCommand handles deployments management commands
func HandleDeploymentsCommand(args []string) {
// Create root command for deployments management
deploymentsCmd := deployments.DeployCmd
deploymentsCmd.Use = "deployments"
deploymentsCmd.Short = "Manage deployments"
deploymentsCmd.Long = "List, get, delete, rollback, and view logs for deployments"
// Add management subcommands
deploymentsCmd.AddCommand(deployments.ListCmd)
deploymentsCmd.AddCommand(deployments.GetCmd)
deploymentsCmd.AddCommand(deployments.DeleteCmd)
deploymentsCmd.AddCommand(deployments.RollbackCmd)
deploymentsCmd.AddCommand(deployments.LogsCmd)
deploymentsCmd.SetArgs(args)
if err := deploymentsCmd.Execute(); err != nil {
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(1)
}
}
// HandleDBCommand handles database commands
func HandleDBCommand(args []string) {
dbCmd := db.DBCmd
dbCmd.SetArgs(args)
if err := dbCmd.Execute(); err != nil {
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(1)
}
}