Production Deployment

Overview

This guide covers deploying ARCA to production environments. The monorepo structure allows you to deploy the backend and frontend independently to different platforms.

Deployment Architecture

Backend

NestJS API deployed to Node.js hosting (Railway, Heroku, VPS)

Frontend

Next.js app deployed to Vercel, Netlify, or similar

Database

PostgreSQL on managed services (Supabase, Neon, AWS RDS)

File Storage

Document storage on S3, Cloudinary, or similar

Pre-Deployment Checklist

Build Test

Test production builds locally:

# Build both applications
npm run build

# Test backend production build
cd apps/backend
npm run start:prod

# Test frontend production build
cd apps/frontend
npm run start

Verify:

No build errors
TypeScript compilation succeeds
Applications start correctly

Database Preparation

Prepare your production database:

PostgreSQL database created
Database user has appropriate permissions
SSL enabled
Automated backups configured
Connection pooling set up (if needed)

Code Quality

Run quality checks:

# Lint check
npm run lint

# Type check
npm run check-types

Backend Deployment

Option 1: Railway

Railway offers easy deployment with automatic SSL and PostgreSQL.

Install Railway CLI

npm i -g @railway/cli
railway login

Create New Project

railway init

Add PostgreSQL

In Railway dashboard:

Click “New” → “Database” → “PostgreSQL”
Copy the DATABASE_URL connection string

Configure Environment Variables

railway variables set DATABASE_URL="postgresql://..."
railway variables set JWT_SECRET="your-secret"
railway variables set JWT_TOKEN_AUDIENCE="arca-api"
railway variables set JWT_TOKEN_ISSUER="arca-backend"
railway variables set JWT_TTL="3600s"
railway variables set PORT="3333"
railway variables set CORS_ORIGIN="https://your-frontend-url.com"
railway variables set NODE_ENV="production"

Configure Build

Create railway.json in project root:

{
  "$schema": "https://railway.app/railway.schema.json",
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "npm install && npm run build -w backend"
  },
  "deploy": {
    "startCommand": "npm run start:prod -w backend",
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 10
  }
}

Deploy

railway up

Railway will:

Build your application
Deploy to production
Provide a public URL

Run Migrations

railway run npm run -w backend prisma migrate deploy

Seed Database

railway run npm run -w backend db:seed

Option 2: Heroku

Install Heroku CLI

# Install
npm install -g heroku

# Login
heroku login

Create Application

# Create app
heroku create arca-backend

# Add PostgreSQL
heroku addons:create heroku-postgresql:mini

Configure Environment

heroku config:set JWT_SECRET="your-secret"
heroku config:set JWT_TOKEN_AUDIENCE="arca-api"
heroku config:set JWT_TOKEN_ISSUER="arca-backend"
heroku config:set JWT_TTL="3600s"
heroku config:set CORS_ORIGIN="https://your-frontend.vercel.app"
heroku config:set NODE_ENV="production"

Configure Buildpack

Create Procfile in project root:

web: cd apps/backend && npm run start:prod
release: cd apps/backend && npx prisma migrate deploy

Deploy

git push heroku main

Seed Database

heroku run npm run -w backend db:seed

Option 3: Docker

Deploy using Docker containers.

Create Backend Dockerfile

Create apps/backend/Dockerfile:

FROM node:18-alpine AS builder

WORKDIR /app

# Copy package files
COPY package*.json ./
COPY apps/backend/package*.json ./apps/backend/

# Install dependencies
RUN npm install

# Copy application code
COPY apps/backend ./apps/backend
COPY turbo.json ./

# Generate Prisma Client
WORKDIR /app/apps/backend
RUN npx prisma generate

# Build application
WORKDIR /app
RUN npm run build -w backend

# Production stage
FROM node:18-alpine

WORKDIR /app

# Copy built application
COPY --from=builder /app/apps/backend/dist ./dist
COPY --from=builder /app/apps/backend/node_modules ./node_modules
COPY --from=builder /app/apps/backend/prisma ./prisma
COPY --from=builder /app/apps/backend/package*.json ./

EXPOSE 3333

CMD ["node", "dist/main"]

Create docker-compose.yml

version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: arca_db
      POSTGRES_USER: arca_user
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  backend:
    build:
      context: .
      dockerfile: apps/backend/Dockerfile
    environment:
      DATABASE_URL: postgresql://arca_user:${DB_PASSWORD}@postgres:5432/arca_db
      JWT_SECRET: ${JWT_SECRET}
      JWT_TOKEN_AUDIENCE: arca-api
      JWT_TOKEN_ISSUER: arca-backend
      JWT_TTL: 3600s
      PORT: 3333
      CORS_ORIGIN: ${FRONTEND_URL}
      NODE_ENV: production
    ports:
      - "3333:3333"
    depends_on:
      - postgres
    command: sh -c "npx prisma migrate deploy && node dist/main"

volumes:
  postgres_data:

Deploy

# Build and start
docker-compose up -d

# View logs
docker-compose logs -f backend

# Run seed
docker-compose exec backend npm run db:seed

Frontend Deployment

Option 1: Vercel (Recommended)

Vercel offers the best Next.js deployment experience.

Install Vercel CLI

npm i -g vercel
vercel login

Configure Project

In your repository, create vercel.json:

{
  "buildCommand": "cd ../.. && npm run build -w frontend",
  "devCommand": "cd ../.. && npm run dev -w frontend",
  "installCommand": "cd ../.. && npm install",
  "framework": "nextjs",
  "outputDirectory": "apps/frontend/.next"
}

Set Environment Variables

In Vercel dashboard:

Go to Project Settings → Environment Variables
Add:
- NEXT_PUBLIC_API_URL: Your backend URL (e.g., https://arca-backend.railway.app)
- NEXTAUTH_URL: Your frontend URL (e.g., https://arca.vercel.app)
- NEXTAUTH_SECRET: Generated secret

Deploy

# From project root
vercel

# Or deploy to production
vercel --prod

Or connect your GitHub repository in Vercel dashboard for automatic deployments.

Option 2: Netlify

Install Netlify CLI

npm install -g netlify-cli
netlify login

Configure Build

Create netlify.toml:

[build]
  base = "apps/frontend"
  command = "cd ../.. && npm run build -w frontend"
  publish = "apps/frontend/.next"

[build.environment]
  NODE_VERSION = "18"

[[plugins]]
  package = "@netlify/plugin-nextjs"

Deploy

netlify deploy --prod

Set environment variables in Netlify dashboard.

Option 3: Self-Hosted

Build Frontend

npm run build -w frontend

Create Dockerfile

Create apps/frontend/Dockerfile:

FROM node:18-alpine AS builder

WORKDIR /app

COPY package*.json ./
COPY apps/frontend/package*.json ./apps/frontend/

RUN npm install

COPY apps/frontend ./apps/frontend
COPY turbo.json ./

WORKDIR /app/apps/frontend
RUN npm run build

FROM node:18-alpine

WORKDIR /app

COPY --from=builder /app/apps/frontend/.next ./.next
COPY --from=builder /app/apps/frontend/public ./public
COPY --from=builder /app/apps/frontend/node_modules ./node_modules
COPY --from=builder /app/apps/frontend/package*.json ./

ENV NODE_ENV production
ENV PORT 3000

EXPOSE 3000

CMD ["npm", "start"]

Deploy

docker build -t arca-frontend -f apps/frontend/Dockerfile .
docker run -p 3000:3000 \
  -e NEXT_PUBLIC_API_URL="https://api.arca.com" \
  -e NEXTAUTH_URL="https://arca.com" \
  -e NEXTAUTH_SECRET="your-secret" \
  arca-frontend

Post-Deployment

Verify Deployment

Backend Health Check

curl https://your-backend-url.com

Ensure the API is responding.

Frontend Access

Open your frontend URL in a browser and verify:

Application loads
Can access login page
No console errors

Database Connection

Test a login with default credentials to verify database connectivity.

Change Default Passwords

Immediately change all default user passwords!

Configure Monitoring

Set up monitoring and alerts:

Application Monitoring

Sentry for error tracking
LogRocket for session replay
New Relic for APM

Infrastructure Monitoring

Railway/Heroku built-in metrics
Uptime monitoring (UptimeRobot)
Database performance monitoring

Set Up Backups

Configure automated database backups:

Enable automatic backups on your database provider
Test restore procedure
Document backup/restore process

Environment-Specific Configuration

Production
Staging
Development

# Backend
DATABASE_URL="postgresql://user:pass@prod-db:5432/arca_prod?sslmode=require"
JWT_SECRET="<strong-random-secret>"
JWT_TTL="3600s"
CORS_ORIGIN="https://arca.yourdomain.com"
NODE_ENV="production"

# Frontend
NEXT_PUBLIC_API_URL="https://api.arca.yourdomain.com"
NEXTAUTH_URL="https://arca.yourdomain.com"
NEXTAUTH_SECRET="<strong-random-secret>"

# Backend
DATABASE_URL="postgresql://user:pass@staging-db:5432/arca_staging"
JWT_SECRET="<staging-secret>"
JWT_TTL="24h"
CORS_ORIGIN="https://staging.arca.yourdomain.com"
NODE_ENV="production"

# Frontend
NEXT_PUBLIC_API_URL="https://api-staging.arca.yourdomain.com"
NEXTAUTH_URL="https://staging.arca.yourdomain.com"
NEXTAUTH_SECRET="<staging-secret>"

# Backend
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/arca_dev"
JWT_SECRET="dev-secret"
JWT_TTL="24h"
CORS_ORIGIN="http://localhost:3000"
NODE_ENV="development"

# Frontend
NEXT_PUBLIC_API_URL="http://localhost:3333"
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="dev-secret"

Scaling Considerations

Backend Scaling

Use horizontal scaling (multiple instances)
Implement connection pooling (PgBouncer)
Add Redis for session storage
Use CDN for static assets

Database Scaling

Enable read replicas
Implement connection pooling
Add database indexes for common queries
Consider partitioning for large tables

Frontend Scaling

Vercel automatically handles scaling
Enable Next.js Image Optimization
Use ISR for static content
Implement client-side caching

File Storage

Move to S3/Cloudinary for documents
Use signed URLs for secure access
Implement CDN for file delivery

Troubleshooting

Database Connection Errors

Verify DATABASE_URL is correct
Check SSL mode requirements
Ensure database accepts connections from deployment IP
Verify connection pooling settings

CORS Errors

Verify CORS_ORIGIN exactly matches frontend URL (including protocol)
Don’t include trailing slash
For multiple origins, ensure proper format
Check browser console for exact origin being rejected

Build Failures

Check build logs for specific errors
Verify all dependencies are in package.json
Ensure TypeScript compilation succeeds locally
Check Node.js version matches requirements (>= 18)

Environment Variables Not Loading

Verify variables are set in platform dashboard
Restart application after setting variables
Check variable names (no typos)
For Next.js, ensure NEXT_PUBLIC_ prefix for client-side variables

Security Checklist

Next Steps

After deploying to production, make sure to:

Set up regular database backups
Monitor application logs for errors
Keep dependencies updated for security patches
Review audit logs regularly for compliance
Test disaster recovery procedures

Get Started

Core Features

User Management

Deployment

Development

Production Deployment

Overview

Deployment Architecture

Backend

Frontend

Database

File Storage

Pre-Deployment Checklist

Backend Deployment

Option 1: Railway

Option 2: Heroku

Option 3: Docker

Frontend Deployment

Option 1: Vercel (Recommended)

Option 2: Netlify

Option 3: Self-Hosted

Post-Deployment

Application Monitoring

Infrastructure Monitoring

Environment-Specific Configuration

Scaling Considerations

Backend Scaling

Database Scaling

Frontend Scaling

File Storage

Troubleshooting

Security Checklist

Next Steps

Build docs developers (and LLMs) love

Get Started

Core Features

User Management

Deployment

Development

​Overview

​Deployment Architecture

Backend

Frontend

Database

File Storage

​Pre-Deployment Checklist

​Backend Deployment

​Option 1: Railway

​Option 2: Heroku

​Option 3: Docker

​Frontend Deployment

​Option 1: Vercel (Recommended)

​Option 2: Netlify

​Option 3: Self-Hosted

​Post-Deployment

Application Monitoring

Infrastructure Monitoring

​Environment-Specific Configuration

​Scaling Considerations

Backend Scaling

Database Scaling

Frontend Scaling

File Storage

​Troubleshooting

​Security Checklist

​Next Steps

Build docs developers (and LLMs) love

Overview

Deployment Architecture

Pre-Deployment Checklist

Backend Deployment

Option 1: Railway

Option 2: Heroku

Option 3: Docker

Frontend Deployment

Option 1: Vercel (Recommended)

Option 2: Netlify

Option 3: Self-Hosted

Post-Deployment

Environment-Specific Configuration

Scaling Considerations

Troubleshooting

Security Checklist

Next Steps