Deployment Guide

Complete guide to deploying your Flowfull backend to production.

Overview

Flowfull can be deployed to any platform that supports Node.js/Bun applications. This guide covers the most popular platforms.

Prerequisites

Before deploying:

• ✅ Database configured and migrated
• ✅ Environment variables documented
• ✅ Redis instance (for caching)
• ✅ Flowless instance on Pubflow
• ✅ Tests passing

Platform Guides

Railway

Best for: Quick deployments, PostgreSQL/Redis included

1. Install Railway CLI:

npm install -g @railway/cli

2. Login:

railway login

3. Initialize project:

railway init

4. Add PostgreSQL:

railway add postgresql

5. Add Redis:

railway add redis

6. Set environment variables:

railway variables set FLOWLESS_URL=https://your-instance.pubflow.com
railway variables set BRIDGE_SECRET=your-secret
railway variables set VALIDATION_MODE=STANDARD

7. Deploy:

railway up

Fly.io

Best for: Global edge deployment, low latency

1. Install Fly CLI:

curl -L https://fly.io/install.sh | sh

2. Login:

fly auth login

3. Create app:

fly launch

4. Create Dockerfile:

FROM oven/bun:1 as base
WORKDIR /app

# Install dependencies
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile

# Copy source
COPY . .

# Build (if needed)
RUN bun run build

# Expose port
EXPOSE 3000

# Start
CMD ["bun", "run", "start"]

5. Set secrets:

fly secrets set FLOWLESS_URL=https://your-instance.pubflow.com
fly secrets set BRIDGE_SECRET=your-secret
fly secrets set DATABASE_URL=your-database-url

6. Deploy:

fly deploy

Vercel

Best for: Serverless deployment, Next.js integration

1. Install Vercel CLI:

npm install -g vercel

2. Create vercel.json:

{
  "version": 2,
  "builds": [
    {
      "src": "src/index.ts",
      "use": "@vercel/node"
    }
  ],
  "routes": [
    {
      "src": "/(.*)",
      "dest": "src/index.ts"
    }
  ]
}

3. Deploy:

vercel

4. Set environment variables in Vercel dashboard

AWS (EC2)

Best for: Full control, enterprise deployments

1. Launch EC2 instance (Ubuntu 22.04)

2. SSH into instance:

ssh -i your-key.pem ubuntu@your-instance-ip

3. Install Bun:

curl -fsSL https://bun.sh/install | bash

4. Clone repository:

git clone https://github.com/your-org/your-flowfull.git
cd your-flowfull

5. Install dependencies:

bun install

6. Create .env:

nano .env
# Add your environment variables

7. Run migrations:

bun run migrate

8. Install PM2:

npm install -g pm2

9. Start with PM2:

pm2 start bun --name flowfull -- run start
pm2 save
pm2 startup

Google Cloud Run

Best for: Serverless containers, auto-scaling

1. Install gcloud CLI

2. Create Dockerfile (same as Fly.io)

3. Build and push:

gcloud builds submit --tag gcr.io/PROJECT_ID/flowfull

4. Deploy:

gcloud run deploy flowfull \
  --image gcr.io/PROJECT_ID/flowfull \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars FLOWLESS_URL=https://your-instance.pubflow.com

Environment Variables

Required Variables

# Server
PORT=3000
NODE_ENV=production

# Database
DATABASE_TYPE=postgresql
DATABASE_URL=postgresql://user:password@host:5432/db

# Flowless Integration
FLOWLESS_URL=https://your-instance.pubflow.com
BRIDGE_SECRET=your-bridge-secret-here

# Security
VALIDATION_MODE=STANDARD

Optional Variables

# Cache
CACHE_ENABLED=true
REDIS_URL=redis://host:6379

# PASETO
PASETO_SECRET_KEY=your-paseto-secret

# Logging
LOG_MODE=production

Database Migration

Run migrations before deploying:

# Local
bun run migrate

# Railway
railway run bun run migrate

# Fly.io
fly ssh console -C "bun run migrate"

# Vercel (use Vercel CLI)
vercel env pull .env.production
bun run migrate

Health Checks

Add health check endpoint:

app.get('/health', async (c) => {
  try {
    // Check database
    await db.selectFrom('users').select('id').limit(1).execute();
    
    // Check Redis (if enabled)
    if (process.env.CACHE_ENABLED === 'true') {
      await redis.ping();
    }
    
    return c.json({ 
      status: 'healthy',
      timestamp: new Date().toISOString()
    });
  } catch (error) {
    return c.json({ 
      status: 'unhealthy',
      error: error.message 
    }, 503);
  }
});

Monitoring

Logging

import { logger } from './lib/logger';

app.use('*', async (c, next) => {
  const start = Date.now();
  await next();
  const ms = Date.now() - start;
  
  logger.info({
    method: c.req.method,
    path: c.req.path,
    status: c.res.status,
    duration: ms
  });
});

Error Tracking

Use Sentry for error tracking:

bun add @sentry/node

import * as Sentry from '@sentry/node';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
});

app.onError((err, c) => {
  Sentry.captureException(err);
  return c.json({ error: 'Internal server error' }, 500);
});

Scaling

Horizontal Scaling

Flowfull is designed to scale horizontally:

1. Stateless design - No local state
2. Redis cache - Shared across instances
3. Database pooling - Efficient connections
4. Load balancer - Distribute traffic

Auto-Scaling

Configure auto-scaling based on:

• CPU usage (> 70%)
• Memory usage (> 80%)
• Request rate (> 1000 req/s)

Security

Production Checklist

• ✅ Use HTTPS only
• ✅ Set NODE_ENV=production
• ✅ Use strong BRIDGE_SECRET
• ✅ Enable VALIDATION_MODE=STANDARD or higher
• ✅ Use environment variables for secrets
• ✅ Enable rate limiting
• ✅ Set up CORS properly
• ✅ Use security headers

Security Headers

import { secureHeaders } from 'hono/secure-headers';

app.use('*', secureHeaders());

Rate Limiting

import { rateLimiter } from 'hono-rate-limiter';

app.use('*', rateLimiter({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // Max 100 requests per window
}));

Best Practices

✅ Do

• Use environment variables for configuration
• Run migrations before deployment
• Set up health checks
• Enable monitoring and logging
• Use HTTPS in production
• Set up auto-scaling
• Backup database regularly

❌ Don't

• Hardcode secrets
• Skip migrations
• Deploy without testing
• Use development mode in production
• Ignore error logs
• Skip health checks

Troubleshooting

Deployment Fails

Check:

• Build logs for errors
• Environment variables are set
• Database is accessible
• Dependencies are installed

App Crashes

Check:

• Error logs
• Database connection
• Redis connection (if enabled)
• Memory limits

Slow Performance

Check:

• Database indexes
• Cache hit rate
• Connection pool size
• Instance resources

Next Steps

• Database Setup - Configure production database
• HybridCache - Optimize with caching
• Environment Config - Manage configuration

Need Help?

• 🌐 Notside.com - Professional deployment services
• 📧 Email: contact@notside.com
• 💼 Services: DevOps, infrastructure, scaling