Skip to content

Deployment Guide

How to build, test, and deploy Constellation to production.

Pre-deployment Checklist

  • [ ] All tests pass: bun test:run
  • [ ] ESLint passes: bun lint
  • [ ] TypeScript compiles: bun run build
  • [ ] Coverage > 80%: bun test:coverage
  • [ ] No console errors or warnings
  • [ ] All environment variables set
  • [ ] Documentation updated
  • [ ] Staging environment tested

Building for Production

Local Build

# Build production bundle
bun run build

# Test production build locally
bun run build && bun start

# Open http://localhost:3000

Build Output

.next/               # Compiled Next.js output
│
├── static/          # Static assets
├── server/          # Server-side code
└── standalone/      # Standalone build

Environment Setup

Production Environment Variables

Create .env.production:

# Backend Services
NEXT_PUBLIC_API_URL=https://api.constellation.app
NEXT_PUBLIC_NEO4J_URL=https://graph.constellation.app
NEXT_PUBLIC_SSE_URL=https://events.constellation.app
NEXT_PUBLIC_CRDT_HOCUSPOCUS_URL=wss://collab.constellation.app
NEXT_PUBLIC_AI_API_URL=https://ai.constellation.app

# OAuth
GOOGLE_CLIENT_ID=production_client_id
GOOGLE_CLIENT_SECRET=production_client_secret
GOOGLE_REDIRECT_URI=https://constellation.app/auth/google/callback
GOOGLE_TOKEN_URI=https://oauth2.googleapis.com/token

# Analytics
NEXT_PUBLIC_HOTJAR_ID=production_hotjar_id
NEXT_PUBLIC_SENTRY_DSN=production_sentry_dsn

# Polar
POLAR_ACCESS_TOKEN=production_polar_token
POLAR_SUCCESS_URL=https://constellation.app/success?checkout_id={CHECKOUT_ID}

⚠️ Warning: Never commit secrets. Use platform-specific secret management.

Deployment Platforms

1. Connect Repository

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

# Or push to connected repo and auto-deploy
git push origin main

2. Configure Environment Variables

In Vercel Dashboard: - Settings → Environment Variables - Add production environment variables - Set for Production, Staging, Development

3. Configure Build Settings

Build Command:    bun run build
Output Directory: .next
Node Version:     18.x or 19.x

4. Deploy

# Deploy to staging
vercel --prebuilt

# Deploy to production
vercel prod --prebuilt

AWS Amplify

1. Connect Repository

  • Go to AWS Amplify Console
  • Connect to GitHub repository
  • Select branch to deploy

2. Configure Build Settings

version: 1
frontend:
  phases:
    build:
      commands:
        - npm install -g bun
        - bun install
        - bun run build
  artifacts:
    baseDirectory: .next
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*

3. Set Environment Variables

In Amplify Console: - App settings → Environment variables - Add variables for each environment

4. Deploy

  • Push to connected branch
  • Auto-deploy on push

Docker Deployment

1. Create Dockerfile

# Build stage
FROM node:18-alpine AS builder
RUN npm install -g bun
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install

COPY . .
RUN bun run build

# Runtime stage
FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/public ./public
COPY --from=builder /app/package.json ./package.json

EXPOSE 3000
CMD ["bun", "start"]

2. Build and Push

# Build image
docker build -t constellation:latest .

# Tag for registry
docker tag constellation:latest myregistry.azurecr.io/constellation:latest

# Push to registry
docker push myregistry.azurecr.io/constellation:latest

3. Deploy Container

# Using Docker Compose
docker-compose up -d

# Or deploy to Kubernetes
kubectl apply -f deployment.yaml

CI/CD Pipeline

GitHub Actions Example

Create .github/workflows/deploy.yml:

name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: oven-sh/setup-bun@v1

      - name: Install dependencies
        run: bun install

      - name: Run tests
        run: bun test:run

      - name: Run linter
        run: bun lint

      - name: Build
        run: bun run build

  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: oven-sh/setup-bun@v1

      - name: Install dependencies
        run: bun install

      - name: Build
        run: bun run build

      - name: Deploy to Vercel
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
        run: |
          npm i -g vercel
          vercel --prod --token $VERCEL_TOKEN

Pre-deployment Testing

Staging Environment

# Set staging environment
NODE_ENV=staging

# Copy staging env file
cp .env.staging .env.local

# Build
bun run build

# Test locally
bun start

Smoke Tests

// tests/e2e/smoke.test.ts
describe('Smoke Tests', () => {
  it('should load homepage', async () => {
    const response = await fetch('https://staging.constellation.app');
    expect(response.status).toBe(200);
  });

  it('should connect to API', async () => {
    const response = await fetch('https://api.constellation.app/health');
    expect(response.status).toBe(200);
  });

  it('should load editor', async () => {
    // Load page and check editor loads
  });
});

Performance Testing

# Build analysis
bun run build:analyze

# Check bundle size
bun run size

Monitoring & Logging

Sentry Integration

// src/instrumentation.ts
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  environment: process.env.NODE_ENV,
  tracesSampleRate: 1.0,
  integrations: [
    new Sentry.Replay(),
  ],
});

CloudWatch Logs (AWS)

# View logs
aws logs tail /constellation/frontend --follow

# Search logs
aws logs filter-log-events \
  --log-group-name /constellation/frontend \
  --filter-pattern "ERROR"

Hotjar Analytics

// Already configured in project
// Tracks user behavior and sessions

Scaling Considerations

Static Site Generation (SSG)

// src/app/blog/[slug]/page.tsx
export async function generateStaticParams() {
  const posts = await getPosts();
  return posts.map((post) => ({
    slug: post.slug,
  }));
}

export const revalidate = 3600; // ISR: revalidate every hour

Incremental Static Regeneration (ISR)

export const revalidate = 60; // Revalidate every 60 seconds

Edge Caching

// Cloudflare or CDN configuration
// Cache static assets
// Set cache headers

Rollback Plan

Identify Issue

  1. Check monitoring/error tracking
  2. Review recent changes
  3. Check user reports

Rollback Steps

On Vercel

# View deployments
vercel list

# Rollback to previous deployment
vercel promote <deployment-url>

Manual Rollback

# Redeploy from previous commit
git checkout <previous-commit>
git push origin main

Post-deployment Verification

Checklist

  • [ ] Application loads without errors
  • [ ] API calls succeed
  • [ ] Authentication works
  • [ ] Database connections stable
  • [ ] Real-time features operational
  • [ ] Editor functionality works
  • [ ] Analytics tracking active
  • [ ] Error tracking active
  • [ ] Performance acceptable
  • [ ] No security issues

Performance Benchmarks

Metric Target Actual
FCP (First Contentful Paint) < 1.5s
LCP (Largest Contentful Paint) < 2.5s
TTI (Time to Interactive) < 3.5s
CLS (Cumulative Layout Shift) < 0.1
Bundle Size (gzipped) < 200KB

Maintenance

Regular Tasks

# Update dependencies monthly
bun update

# Review security vulnerabilities
bun audit

# Check for outdated packages
bun outdated

# Run full test suite
bun test:run

Database Backups

# Automated daily backups
# Keep 30-day retention
# Test restore procedures monthly

Log Rotation

# Configure log rotation
# Keep 7 days of logs
# Archive older logs to storage

Disaster Recovery

Backup Strategy

  1. Database: Daily automated backups
  2. Code: Git repository (GitHub)
  3. Assets: CDN (versioned)
  4. Secrets: Encrypted secrets manager

Recovery Time Objective (RTO)

  • Critical outage: < 30 minutes
  • Degraded service: < 2 hours
  • Full recovery: < 24 hours

Recovery Procedures

  1. Identify issue
  2. Stop current deployment
  3. Restore from backup
  4. Verify functionality
  5. Run smoke tests
  6. Notify users

Cost Optimization

Recommendations

  1. CDN: Use edge caching
  2. Images: Optimize with next/image
  3. Code splitting: Automatic via Next.js
  4. Database: Connection pooling
  5. Storage: Archive old logs

Monitoring Costs

  • Vercel: Check project usage
  • AWS: Set up cost alarms
  • Track API call volumes
  • Monitor data transfer

Last Updated: January 2026
Questions? Check TROUBLESHOOTING.md or ask the team