Skip to main content

Deployment Guidelines

This guide helps you understand what types of applications are suitable for deployment on Flux-Orbit and the architectural requirements.

Core Principle: Stateless Applications​

Flux-Orbit is designed for stateless applications that run in containers on the Flux Network. Your application code and dependencies are containerized, but persistent data must be stored externally.

What Can Be Deployed​

Web Applications​

  • Frontend apps: React, Vue, Angular, Svelte, Next.js, Nuxt
  • Static sites: HTML/CSS/JS, documentation sites, landing pages
  • Server-rendered apps: Next.js SSR, Nuxt SSR, SvelteKit

Backend APIs​

  • REST APIs: Express, FastAPI, Django REST, Rails API, Laravel, Gin, Actix-web
  • GraphQL APIs: Apollo Server, Hasura client apps
  • Microservices: Stateless services that process requests and return responses

Real-time Applications​

  • WebSocket servers: Chat applications, live updates, notifications
  • SSE (Server-Sent Events): Real-time data streaming

What Should NOT Be Deployed​

Applications that store critical data locally:

  • Databases (PostgreSQL, MySQL, MongoDB) - Use Flux Clustered DBs or hosted database services instead
  • File storage systems - Use Flux Storage or similar instead
  • Session stores - Use Redis, database sessions, or JWT tokens instead
  • Stateful applications with local file writes - Uploads will be lost on redeploy

Data Storage: Use External Services​

Since containers are ephemeral and can be redeployed at any time, all persistent data must be stored externally.

Database Storage​

Use Flux Database services:

Environment Variables:
  # PostgreSQL
  DATABASE_URL: postgresql://user:pass@your-db-host.com:5432/dbname

  # MySQL
  DATABASE_URL: mysql://user:pass@your-db-host.com:3306/dbname

  # MongoDB
  MONGODB_URI: mongodb://user:pass@your-db-host.com:27017/dbname

Popular database hosting options:

  • PostgreSQL: Flux PostgreSQL Cluster, Supabase, Neon, Railway
  • MySQL: Flux Shared DB, PlanetScale, Railway, AWS RDS
  • MongoDB: Flux MongoDB Cluster, MongoDB Atlas
  • Redis: Upstash, Redis Cloud

Session Management​

For stateful user sessions: Option 1: External Session Store (Recommended)

Environment Variables:
  # Redis for sessions
  REDIS_URL: redis://your-redis-host.com:6379
  SESSION_STORE: redis

Option 2: JWT Tokens (Stateless)

// No server-side storage needed
// Sessions encoded in signed tokens

Option 3: Database Sessions

Environment Variables:
  # Store sessions in your database
  DATABASE_URL: postgresql://...
  SESSION_STORE: database

Architecture Patterns​

Good: Stateless API with External Database​

Flux-Orbit (Your API) - Stateless
Express.js App
Stateless Design
→
PostgreSQL
Example:
  • Express.js API
  • Connects to PostgreSQL on Supabase
  • Uses Redis on Upstash for caching
  • Uploads files to Cloudflare R2

Bad: Application with Local Storage​

Flux-Orbit - Your App
SQLite DB
← Data lost on redeploy!
Local files
← Uploads lost!

Common Use Cases​

E-commerce Application​

# Your Flux-Orbit app
GIT_REPO_URL: https://github.com/you/ecommerce-app
APP_PORT: 3000

# External services
DATABASE_URL: postgresql://shop_db@neon.tech/shop
REDIS_URL: redis://cache@upstash.io:6379
S3_BUCKET: product-images
STRIPE_API_KEY: sk_live_...

What's deployed: Node.js/Python/Ruby app (stateless) What's external: Database, cache, file storage, payments

SaaS Dashboard​

# Your Flux-Orbit app
GIT_REPO_URL: https://github.com/you/saas-dashboard
APP_PORT: 8000

# External services
DATABASE_URL: postgresql://users@supabase.co/prod
REDIS_URL: redis://sessions@upstash.io:6379
SMTP_HOST: smtp.sendgrid.net

What's deployed: Python FastAPI backend (stateless) What's external: User database, session cache, email service

Real-time Chat Application​

# Your Flux-Orbit app
GIT_REPO_URL: https://github.com/you/chat-app
APP_PORT: 3000

# External services
DATABASE_URL: postgresql://chat@neon.tech/messages
REDIS_URL: redis://pubsub@upstash.io:6379

What's deployed: WebSocket server (stateless) What's external: Message history, pub/sub for real-time events

Quick Checklist​

Before deploying, verify:

  • Application doesn't write files to local disk (or writes are temporary/cacheable)
  • Database connection uses DATABASE_URL environment variable
  • File uploads go to S3/R2/external storage
  • Sessions use Redis, database, or JWT tokens (not local memory)
  • Application can handle being restarted at any time
  • No hardcoded localhost connections (use environment variables)

Migration Tips​

If your app currently uses local storage:

SQLite → PostgreSQL/MySQL​

# Export SQLite data
sqlite3 mydb.db .dump > dump.sql
# Import to PostgreSQL (adjust syntax)
psql $DATABASE_URL < dump.sql
# Update app to use DATABASE_URL

Local Files → S3/R2​

// Before: Local storage
fs.writeFile('./uploads/image.jpg', data);
// After: S3 storage
await s3.upload({
  Bucket: process.env.S3_BUCKET,
  Key: 'image.jpg',
  Body: data
});

Memory Sessions → Redis​

// Before: In-memory sessions
const session = require('express-session');
app.use(session({ store: new MemoryStore() }));
// After: Redis sessions
const RedisStore = require('connect-redis').default;
app.use(session({
  store: new RedisStore({ url: process.env.REDIS_URL })
}));

Next Steps​