How To Deploy - ruvnet/ruv-FANN GitHub Wiki
How to Deploy ruv-FANN to Production
A comprehensive production deployment guide covering cloud platforms, containerization, monitoring, and scaling strategies.
Deployment Overview
ruv-FANN supports multiple deployment models:
- Standalone Services: Single-node neural processing
- Swarm Clusters: Multi-node distributed intelligence
- Edge Deployment: IoT and edge computing scenarios
- Serverless Functions: Event-driven neural processing
- Hybrid Cloud: Mixed on-premise and cloud deployments
Prerequisites
Production Environment Requirements
| Component | Minimum | Recommended |
|---|---|---|
| CPU | 4 cores, 8GB RAM | 16+ cores, 32GB+ RAM |
| Network | 100 Mbps | 10 Gbps for swarm coordination |
| Storage | 50GB SSD | 200GB+ NVMe SSD |
| OS | Ubuntu 20.04+ | Ubuntu 22.04 LTS |
Security Prerequisites
# SSL/TLS certificates
sudo apt install certbot python3-certbot-nginx
# Firewall configuration
sudo ufw enable
sudo ufw allow 22,80,443,8080/tcp
sudo ufw allow 3000:4000/tcp # Swarm coordination ports
Docker Deployment
1. Single Node Deployment
Create Production Dockerfile
# /production/Dockerfile
FROM rust:1.75 as builder
WORKDIR /app
COPY . .
# Build optimized release
RUN cargo build --release --all --features production
FROM debian:bookworm-slim
# Install runtime dependencies
RUN apt-get update && apt-get install -y \
ca-certificates \
libssl3 \
&& rm -rf /var/lib/apt/lists/*
# Copy built binaries
COPY --from=builder /app/target/release/ruv-swarm /usr/local/bin/
COPY --from=builder /app/target/release/ruv-fann /usr/local/bin/
# Create non-root user
RUN useradd -r -s /bin/false ruv
USER ruv
EXPOSE 8080 3000-3010
CMD ["ruv-swarm", "serve", "--production"]
Build and Deploy
# Build production image
docker build -f production/Dockerfile -t ruv-fann:production .
# Run with production settings
docker run -d \
--name ruv-fann-prod \
--restart unless-stopped \
-p 8080:8080 \
-p 3000-3010:3000-3010 \
-v /data/ruv-fann:/data \
-e RUV_ENV=production \
-e RUV_LOG_LEVEL=info \
ruv-fann:production
2. Multi-Container Swarm Setup
Docker Compose Configuration
# docker-compose.prod.yml
version: '3.8'
services:
ruv-coordinator:
image: ruv-fann:production
command: ["ruv-swarm", "coordinator", "--production"]
environment:
- RUV_ROLE=coordinator
- RUV_CLUSTER_SIZE=3
- RUV_REDIS_URL=redis://redis:6379
depends_on:
- redis
ports:
- "8080:8080"
networks:
- ruv-network
ruv-worker:
image: ruv-fann:production
command: ["ruv-swarm", "worker", "--production"]
environment:
- RUV_ROLE=worker
- RUV_COORDINATOR=ruv-coordinator:3000
- RUV_REDIS_URL=redis://redis:6379
depends_on:
- ruv-coordinator
- redis
deploy:
replicas: 3
networks:
- ruv-network
redis:
image: redis:7-alpine
command: redis-server --appendonly yes
volumes:
- redis-data:/data
networks:
- ruv-network
nginx:
image: nginx:alpine
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
- ./ssl:/etc/ssl/certs:ro
depends_on:
- ruv-coordinator
networks:
- ruv-network
volumes:
redis-data:
networks:
ruv-network:
driver: bridge
Deploy Multi-Container Setup
# Deploy the stack
docker-compose -f docker-compose.prod.yml up -d
# Scale workers dynamically
docker-compose -f docker-compose.prod.yml up -d --scale ruv-worker=5
# Monitor deployment
docker-compose -f docker-compose.prod.yml logs -f
Kubernetes Deployment
1. Kubernetes Manifests
Namespace and ConfigMap
# k8s/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
name: ruv-fann
---
apiVersion: v1
kind: ConfigMap
metadata:
name: ruv-config
namespace: ruv-fann
data:
config.toml: |
[production]
log_level = "info"
max_agents = 50
cluster_discovery = "kubernetes"
[swarm]
topology = "mesh"
heartbeat_interval = "5s"
coordination_timeout = "30s"
[neural]
model_cache_size = "1GB"
batch_size = 32
optimization_level = "high"
Deployment Configuration
# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: ruv-swarm-coordinator
namespace: ruv-fann
spec:
replicas: 1
selector:
matchLabels:
app: ruv-coordinator
template:
metadata:
labels:
app: ruv-coordinator
spec:
containers:
- name: coordinator
image: ruv-fann:production
command: ["ruv-swarm", "coordinator", "--kubernetes"]
ports:
- containerPort: 8080
- containerPort: 3000
env:
- name: RUV_ROLE
value: "coordinator"
- name: KUBERNETES_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
volumeMounts:
- name: config
mountPath: /etc/ruv
resources:
requests:
memory: "2Gi"
cpu: "1000m"
limits:
memory: "4Gi"
cpu: "2000m"
volumes:
- name: config
configMap:
name: ruv-config
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: ruv-swarm-workers
namespace: ruv-fann
spec:
replicas: 3
selector:
matchLabels:
app: ruv-worker
template:
metadata:
labels:
app: ruv-worker
spec:
containers:
- name: worker
image: ruv-fann:production
command: ["ruv-swarm", "worker", "--kubernetes"]
env:
- name: RUV_ROLE
value: "worker"
- name: RUV_COORDINATOR
value: "ruv-coordinator-service:3000"
volumeMounts:
- name: config
mountPath: /etc/ruv
resources:
requests:
memory: "4Gi"
cpu: "2000m"
limits:
memory: "8Gi"
cpu: "4000m"
volumes:
- name: config
configMap:
name: ruv-config
Services and Ingress
# k8s/service.yaml
apiVersion: v1
kind: Service
metadata:
name: ruv-coordinator-service
namespace: ruv-fann
spec:
selector:
app: ruv-coordinator
ports:
- name: http
port: 8080
targetPort: 8080
- name: coordination
port: 3000
targetPort: 3000
type: ClusterIP
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: ruv-ingress
namespace: ruv-fann
annotations:
kubernetes.io/ingress.class: nginx
cert-manager.io/cluster-issuer: letsencrypt-prod
nginx.ingress.kubernetes.io/rate-limit: "100"
spec:
tls:
- hosts:
- ruv-api.yourdomain.com
secretName: ruv-tls
rules:
- host: ruv-api.yourdomain.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: ruv-coordinator-service
port:
number: 8080
2. Deploy to Kubernetes
# Apply all manifests
kubectl apply -f k8s/
# Wait for deployment
kubectl rollout status deployment/ruv-swarm-coordinator -n ruv-fann
kubectl rollout status deployment/ruv-swarm-workers -n ruv-fann
# Check status
kubectl get pods -n ruv-fann
kubectl get services -n ruv-fann
kubectl get ingress -n ruv-fann
3. Horizontal Pod Autoscaler
# k8s/hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
name: ruv-workers-hpa
namespace: ruv-fann
spec:
scaleTargetRef:
apiVersion: apps/v1
kind: Deployment
name: ruv-swarm-workers
minReplicas: 3
maxReplicas: 20
metrics:
- type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: 70
- type: Resource
resource:
name: memory
target:
type: Utilization
averageUtilization: 80
Cloud Platform Deployments
1. AWS Deployment
ECS Fargate Setup
{
"family": "ruv-fann-task",
"networkMode": "awsvpc",
"requiresCompatibilities": ["FARGATE"],
"cpu": "2048",
"memory": "4096",
"executionRoleArn": "arn:aws:iam::ACCOUNT:role/ecsTaskExecutionRole",
"taskRoleArn": "arn:aws:iam::ACCOUNT:role/ecsTaskRole",
"containerDefinitions": [
{
"name": "ruv-coordinator",
"image": "YOUR_ECR_URI/ruv-fann:production",
"portMappings": [
{
"containerPort": 8080,
"protocol": "tcp"
}
],
"environment": [
{
"name": "RUV_ENV",
"value": "production"
},
{
"name": "RUV_ROLE",
"value": "coordinator"
}
],
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-group": "/ecs/ruv-fann",
"awslogs-region": "us-west-2",
"awslogs-stream-prefix": "ecs"
}
}
}
]
}
Deploy to ECS
# Register task definition
aws ecs register-task-definition --cli-input-json file://ecs-task.json
# Create ECS service
aws ecs create-service \
--cluster ruv-cluster \
--service-name ruv-fann-service \
--task-definition ruv-fann-task:1 \
--desired-count 3 \
--launch-type FARGATE \
--network-configuration "awsvpcConfiguration={subnets=[subnet-12345],securityGroups=[sg-12345],assignPublicIp=ENABLED}"
# Setup load balancer
aws elbv2 create-target-group \
--name ruv-fann-targets \
--protocol HTTP \
--port 8080 \
--vpc-id vpc-12345 \
--target-type ip
2. Google Cloud Platform
Cloud Run Deployment
# Build and push to Container Registry
docker build -t gcr.io/PROJECT_ID/ruv-fann:production .
docker push gcr.io/PROJECT_ID/ruv-fann:production
# Deploy to Cloud Run
gcloud run deploy ruv-fann \
--image gcr.io/PROJECT_ID/ruv-fann:production \
--platform managed \
--region us-central1 \
--memory 4Gi \
--cpu 2 \
--max-instances 10 \
--allow-unauthenticated \
--set-env-vars RUV_ENV=production
GKE Deployment
# Create GKE cluster
gcloud container clusters create ruv-cluster \
--num-nodes 3 \
--machine-type n1-standard-4 \
--enable-autoscaling \
--min-nodes 1 \
--max-nodes 10
# Deploy to GKE
kubectl apply -f k8s/
3. Azure Deployment
Container Instances
# Create resource group
az group create --name ruv-fann-rg --location eastus
# Deploy container instance
az container create \
--resource-group ruv-fann-rg \
--name ruv-fann-instance \
--image ruv-fann:production \
--cpu 2 \
--memory 4 \
--ports 8080 \
--ip-address public \
--environment-variables RUV_ENV=production
Edge and IoT Deployment
1. Raspberry Pi Deployment
Cross-Compilation Setup
# Install cross-compilation tools
rustup target add aarch64-unknown-linux-gnu
sudo apt install gcc-aarch64-linux-gnu
# Build for ARM64
export CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc
cargo build --target aarch64-unknown-linux-gnu --release --features embedded
Deploy to Pi
# Copy binary to Pi
scp target/aarch64-unknown-linux-gnu/release/ruv-swarm [email protected]:~/
# SSH to Pi and setup
ssh [email protected]
sudo mv ruv-swarm /usr/local/bin/
sudo chmod +x /usr/local/bin/ruv-swarm
# Create systemd service
sudo tee /etc/systemd/system/ruv-swarm.service > /dev/null <<EOF
[Unit]
Description=RUV-FANN Swarm Agent
After=network.target
[Service]
Type=simple
User=pi
ExecStart=/usr/local/bin/ruv-swarm worker --embedded
Restart=always
RestartSec=5
Environment=RUV_ENV=edge
[Install]
WantedBy=multi-user.target
EOF
# Enable and start service
sudo systemctl enable ruv-swarm
sudo systemctl start ruv-swarm
2. WASM Edge Deployment
Build WASM Module
# Build optimized WASM
cd Semantic_Cartan_Matrix
wasm-pack build --target web --release --features wasm-edge
# Optimize for size
wasm-opt -Os -o pkg/semantic_cartan_matrix_bg.wasm pkg/semantic_cartan_matrix_bg.wasm
Edge Worker Configuration
// edge-worker.js
import init, { SwarmWorker } from './pkg/semantic_cartan_matrix.js';
export default {
async fetch(request, env) {
await init();
const worker = new SwarmWorker();
const result = await worker.process_request(await request.json());
return new Response(JSON.stringify(result), {
headers: { 'Content-Type': 'application/json' }
});
}
};
Monitoring and Observability
1. Prometheus Setup
# monitoring/prometheus.yml
global:
scrape_interval: 15s
scrape_configs:
- job_name: 'ruv-fann'
static_configs:
- targets: ['ruv-coordinator:8080']
metrics_path: /metrics
scrape_interval: 5s
- job_name: 'ruv-workers'
kubernetes_sd_configs:
- role: pod
namespaces:
names: ['ruv-fann']
relabel_configs:
- source_labels: [__meta_kubernetes_pod_label_app]
action: keep
regex: ruv-worker
2. Grafana Dashboard
{
"dashboard": {
"id": null,
"title": "RUV-FANN Swarm Metrics",
"panels": [
{
"title": "Swarm Coordination Rate",
"type": "graph",
"targets": [
{
"expr": "rate(ruv_swarm_coordination_total[5m])",
"legendFormat": "{{instance}}"
}
]
},
{
"title": "Neural Processing Latency",
"type": "graph",
"targets": [
{
"expr": "histogram_quantile(0.95, rate(ruv_neural_processing_duration_seconds_bucket[5m]))",
"legendFormat": "95th percentile"
}
]
}
]
}
}
3. Health Checks and Alerts
# k8s/health-check.yaml
apiVersion: v1
kind: Service
metadata:
name: ruv-health-check
spec:
selector:
app: ruv-coordinator
ports:
- port: 8080
targetPort: 8080
---
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: ruv-metrics
spec:
selector:
matchLabels:
app: ruv-coordinator
endpoints:
- port: metrics
interval: 10s
Security Hardening
1. TLS/SSL Configuration
# Generate SSL certificates
openssl req -x509 -nodes -days 365 -newkey rsa:4096 \
-keyout /etc/ssl/private/ruv-fann.key \
-out /etc/ssl/certs/ruv-fann.crt \
-subj "/C=US/ST=CA/L=SF/O=RUV/CN=ruv-api.yourdomain.com"
# Configure nginx SSL
cat > /etc/nginx/sites-available/ruv-fann << EOF
server {
listen 443 ssl http2;
server_name ruv-api.yourdomain.com;
ssl_certificate /etc/ssl/certs/ruv-fann.crt;
ssl_certificate_key /etc/ssl/private/ruv-fann.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512;
location / {
proxy_pass http://localhost:8080;
proxy_set_header Host \$host;
proxy_set_header X-Real-IP \$remote_addr;
}
}
EOF
2. Network Security
# Configure firewall rules
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp # SSH
sudo ufw allow 80/tcp # HTTP
sudo ufw allow 443/tcp # HTTPS
sudo ufw allow from 10.0.0.0/8 to any port 3000:3010 # Swarm coordination (internal)
sudo ufw enable
3. Container Security
# Security-hardened Dockerfile
FROM rust:1.75 as builder
WORKDIR /app
COPY . .
RUN cargo build --release --features production,security-hardened
FROM gcr.io/distroless/cc-debian12
COPY --from=builder /app/target/release/ruv-swarm /ruv-swarm
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/ruv-swarm"]
Performance Tuning
1. System Optimization
# Kernel parameter tuning
echo 'net.core.rmem_max = 134217728' >> /etc/sysctl.conf
echo 'net.core.wmem_max = 134217728' >> /etc/sysctl.conf
echo 'net.ipv4.tcp_rmem = 4096 87380 134217728' >> /etc/sysctl.conf
echo 'net.ipv4.tcp_wmem = 4096 65536 134217728' >> /etc/sysctl.conf
echo 'vm.swappiness = 10' >> /etc/sysctl.conf
sysctl -p
2. Application Configuration
# /etc/ruv/production.toml
[performance]
worker_threads = 16
max_connections = 10000
connection_pool_size = 100
neural_cache_size = "2GB"
batch_processing = true
batch_size = 64
[optimization]
simd_enabled = true
gpu_acceleration = "auto"
memory_pool = "large"
compression = "lz4"
Backup and Disaster Recovery
1. Data Backup Strategy
# Create backup script
cat > /usr/local/bin/ruv-backup.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="/backup/ruv-fann/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"
# Backup configuration
cp -r /etc/ruv "$BACKUP_DIR/config"
# Backup neural models
cp -r /data/models "$BACKUP_DIR/models"
# Backup metrics data
docker exec ruv-redis redis-cli BGSAVE
cp /data/redis/dump.rdb "$BACKUP_DIR/redis-dump.rdb"
# Compress and upload
tar -czf "$BACKUP_DIR.tar.gz" "$BACKUP_DIR"
aws s3 cp "$BACKUP_DIR.tar.gz" s3://ruv-backups/
EOF
chmod +x /usr/local/bin/ruv-backup.sh
# Schedule daily backups
echo "0 2 * * * /usr/local/bin/ruv-backup.sh" | crontab -
2. Disaster Recovery Plan
# Restore from backup
RESTORE_DATE="20240101_020000"
aws s3 cp s3://ruv-backups/ruv-fann-$RESTORE_DATE.tar.gz /tmp/
tar -xzf /tmp/ruv-fann-$RESTORE_DATE.tar.gz
# Restore configuration
sudo cp -r /tmp/ruv-fann-$RESTORE_DATE/config/* /etc/ruv/
# Restore neural models
sudo cp -r /tmp/ruv-fann-$RESTORE_DATE/models/* /data/models/
# Restart services
sudo systemctl restart ruv-swarm
docker-compose restart
This comprehensive deployment guide covers production-ready deployment scenarios with proper security, monitoring, and disaster recovery considerations.