Backend Deployment

This guide covers deploying the unified backend (apps/ai) to production using Fly.io. The unified backend consolidates all services (AI, Move blockchain, IPFS storage, database, notifications, and authentication) into a single deployment.

Prerequisites

Fly.io CLI: Install from fly.io/docs/hands-on/install-flyctl
Docker: Required for building images
pnpm: Package manager for dependencies
PostgreSQL: Database for production (Fly.io PostgreSQL recommended)

Project Structure

The unified backend is located at apps/ai and includes:

Express server with all route modules
Helia IPFS node integration
Drizzle ORM for database management
Performance tracking utilities
Activity monitoring service

Database Setup

1. Create PostgreSQL Database

# Create a PostgreSQL app on Fly.io
fly postgres create --name cubed-db --region ord

# Attach it to your backend app (create the app first if needed)
fly postgres attach cubed-db --app cubed-backend

2. Run Database Migrations

# Generate migration files
cd apps/ai
pnpm db:generate

# Apply migrations to database
pnpm db:push

# Optional: Open Drizzle Studio to verify schema
pnpm db:studio

Deployment Steps

1. Authenticate with Fly.io

fly auth login

2. Initial Deployment

# Navigate to the unified backend
cd apps/ai

# Launch the application (first time only)
fly launch --name cubed-backend

The fly launch command will:

Detect your Dockerfile
Create a fly.toml configuration file
Provision the app on Fly.io
Deploy the initial version

3. Subsequent Deployments

# From the backend directory
cd apps/ai
fly deploy

# Or from project root using the convenience script
pnpm deploy:ai

Environment Variables

Set all required environment variables as Fly.io secrets:

Required Secrets

# OpenAI API Key (required for AI chat)
fly secrets set OPENAI_API_KEY="sk-your-openai-api-key"

# Privy Authentication (required for user auth)
fly secrets set PRIVY_APP_ID="your-privy-app-id"
fly secrets set PRIVY_APP_SECRET="your-privy-app-secret"

# Database Connection (required)
fly secrets set DATABASE_URL="postgresql://user:pass@host:5432/db"

# Production Configuration
fly secrets set NODE_ENV="production"
fly secrets set PORT="3000"

Optional Secrets

# IPFS API Key (for additional upload security)
fly secrets set IPFS_API_KEY="your-ipfs-api-key"

# Custom server configuration
fly secrets set HOST="0.0.0.0"

Fly.io Configuration

fly.toml Example

app = "cubed-backend"
primary_region = "ord"

[build]
  dockerfile = "Dockerfile"

[env]
  PORT = "3000"
  NODE_ENV = "production"

[services]
  internal_port = 3000
  protocol = "tcp"

  [[services.ports]]
    port = 80
    handlers = ["http"]
    force_https = true

  [[services.ports]]
    port = 443
    handlers = ["tls", "http"]

[services.concurrency]
  type = "requests"
  hard_limit = 1000
  soft_limit = 500

[mounts]
  source = "helia_data"
  destination = "/data/helia"

Volume for IPFS Data

Create a persistent volume for Helia IPFS data:

# Create volume for IPFS data persistence
fly volumes create helia_data --size 10 --region ord

# The volume will be automatically mounted at /data/helia

Verifying Deployment

Health Check

# Check if the backend is responding
curl https://cubed-backend.fly.dev/health

# Expected response: {"status": "ok"}

Full API Check

# Test all major endpoints
curl https://cubed-backend.fly.dev/

# This returns a JSON object with all available endpoints

Database Verification

# Connect to database and verify tables exist
fly postgres connect --app cubed-db

# In psql:
# \dt  # Should show: users, devices, deviceTokens, entries

Monitoring & Logging

View Application Logs

# Backend application logs
fly logs --app cubed-backend

# Database logs
fly postgres logs --app cubed-db

Performance Monitoring

The backend includes automatic performance tracking. Monitor timing logs:

[timing] POST /api/ai/chat - 2.3s (streaming response)
[timing] GET /api/database/entries - 45ms
[timing] POST /api/move/generate-hash - 120ms

Resource Monitoring

# Check app status and resources
fly status --app cubed-backend

# Monitor scaling
fly scale show --app cubed-backend

Scaling Configuration

Horizontal Scaling

# Scale to multiple instances
fly scale count 3 --app cubed-backend

# Configure autoscaling based on CPU
fly autoscale set min=1 max=10 --app cubed-backend

Database Scaling

# Upgrade PostgreSQL plan
fly postgres update --vm-size dedicated-cpu-1x --volume-size 10 --app cubed-db

Troubleshooting

Common Issues

Database Connection Failed

# Check database status
fly postgres status --app cubed-db

# Verify DATABASE_URL secret
fly secrets list --app cubed-backend

# Test database connectivity
fly ssh console --app cubed-backend -C "pnpm db:studio --help"

Application Won't Start

# Check for missing environment variables
fly secrets list --app cubed-backend

# View detailed startup logs
fly logs --app cubed-backend --instance-id <instance-id>

IPFS Initialization Issues

# Check volume mounting
fly volumes list --app cubed-backend

# Verify Helia startup logs
fly logs --app cubed-backend | grep -i helia

High Memory Usage

# Check memory usage
fly checks list --app cubed-backend

# Adjust scaling or increase instance size
fly scale memory 1024 --app cubed-backend

Build Issues

Docker Build Fails

Verify Dockerfile exists in apps/ai/
Check pnpm-lock.yaml is up to date

Ensure native dependencies build correctly:

# Ensure proper build for node-datachannel
RUN apt-get update && apt-get install -y python3 make g++

Lockfile Issues

# Regenerate lockfile if needed
cd apps/ai
rm pnpm-lock.yaml
pnpm install

Rollback Deployment

# List releases
fly releases --app cubed-backend

# Rollback to previous version
fly releases rollback <version-id> --app cubed-backend

Security Best Practices

Network Security

All traffic is automatically HTTPS via Fly.io
Database connections use SSL/TLS
Internal services communicate securely

Secret Management

Use Fly.io secrets for all sensitive data
Rotate API keys regularly
Never commit secrets to version control

Access Control

Row Level Security (RLS) ensures data isolation
Privy authentication validates all user requests
API keys protect IPFS upload operations

Backup & Recovery

Database Backups

# Create manual backup
fly postgres create-backup --app cubed-db

# List available backups
fly postgres backups --app cubed-db

# Restore from backup
fly postgres restore <backup-id> --app cubed-db

Application Backups

# Backup volume data (IPFS data)
fly volumes snapshots create helia_data --app cubed-backend