Moai Platform Deployment

Decision Guide

By Application Type

Web Applications (Frontend + API):

• Next.js → Vercel (optimal integration)
• React/Vue with custom API → Railway (flexible)
• Real-time collaborative → Convex + Vercel

Mobile Backends:

• REST/GraphQL → Railway (stable connections)
• Real-time sync → Convex (reactive queries)
• Edge API → Vercel (global latency)

Full-Stack Monoliths:

• Containerized → Railway (Docker support)
• Serverless → Vercel (Next.js API routes)
• Real-time → Convex (built-in reactivity)

By Infrastructure Needs

Compute Requirements:

• Edge compute → Vercel (30+ edge locations)
• Custom runtimes → Railway (Docker flexibility)
• Serverless TypeScript → Convex (managed runtime)

Storage Requirements:

• Redis/KV → Vercel KV or Railway
• PostgreSQL → Vercel Postgres or Railway
• File storage → Vercel Blob or Railway volumes
• Document DB → Convex (built-in)

Networking Requirements:

• CDN distribution → Vercel (built-in)
• Private networking → Railway (service mesh)
• Real-time WebSocket → Convex (built-in) or Railway

Common Deployment Patterns

Pattern 1: Next.js with Database

Stack: Vercel + Vercel Postgres/KV

Setup:

1. Deploy Next.js app to Vercel
2. Provision Vercel Postgres for database
3. Use Vercel KV for session/cache
4. Configure environment variables
5. Enable ISR for dynamic content

Best For: Web apps with standard database needs, e-commerce, content sites

Pattern 2: Containerized Multi-Service

Stack: Railway + Docker

Setup:

1. Create multi-stage Dockerfile
2. Configure railway.toml for services
3. Set up private networking
4. Configure persistent volumes
5. Enable auto-scaling

Best For: Microservices, complex backends, custom tech stacks

Pattern 3: Real-Time Collaborative App

Stack: Convex + Vercel/Railway (frontend)

Setup:

1. Initialize Convex backend
2. Define schema and server functions
3. Deploy frontend to Vercel/Railway
4. Configure Convex provider
5. Implement optimistic updates

Best For: Collaborative tools, live dashboards, chat applications

Pattern 4: Hybrid Edge + Container

Stack: Vercel (frontend/edge) + Railway (backend services)

Setup:

1. Deploy Next.js frontend to Vercel
2. Deploy backend services to Railway
3. Configure CORS and API endpoints
4. Set up edge middleware for routing
5. Use private networking for Railway

Best For: High-performance apps, global distribution with complex backends

Pattern 5: Serverless Full-Stack

Stack: Vercel (frontend + API routes) + Convex (backend)

Setup:

1. Build Next.js app with API routes
2. Initialize Convex for data layer
3. Configure authentication (Clerk/Auth0)
4. Deploy frontend to Vercel
5. Connect Convex client

Best For: Rapid prototyping, startups, real-time web apps

Essential Configuration

Vercel Quick Start

vercel.json:

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": "nextjs",
  "regions": ["iad1", "sfo1", "fra1"],
  "functions": {
    "app/api/**/*.ts": {
      "memory": 1024,
      "maxDuration": 10
    }
  }
}

Edge Function:

export const runtime = "edge"
export const preferredRegion = ["iad1", "sfo1"]

export async function GET(request: Request) {
  const country = request.geo?.country || "Unknown"
  return Response.json({ country })
}

Railway Quick Start

railway.toml:

[build]
builder = "DOCKERFILE"
dockerfilePath = "Dockerfile"

[deploy]
healthcheckPath = "/health"
healthcheckTimeout = 100
restartPolicyType = "ON_FAILURE"
numReplicas = 2

[deploy.resources]
memory = "2GB"
cpu = "2.0"

Multi-Stage Dockerfile:

# Builder stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Runner stage
FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production
RUN addgroup -g 1001 -S nodejs && adduser -S appuser -u 1001
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
USER appuser
EXPOSE 3000
CMD ["node", "dist/main.js"]

Convex Quick Start

convex/schema.ts:

import { defineSchema, defineTable } from "convex/server"
import { v } from "convex/values"

export default defineSchema({
  messages: defineTable({
    text: v.string(),
    userId: v.id("users"),
    timestamp: v.number(),
  })
    .index("by_timestamp", ["timestamp"])
    .searchIndex("search_text", {
      searchField: "text",
      filterFields: ["userId"],
    }),
})

React Integration:

import { useQuery, useMutation } from "convex/react"
import { api } from "../convex/_generated/api"

export function Messages() {
  const messages = useQuery(api.messages.list)
  const sendMessage = useMutation(api.messages.send)

  if (!messages) return <div>Loading...</div>

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg._id}>{msg.text}</div>
      ))}
    </div>
  )
}

CI/CD Integration

GitHub Actions - Vercel