Skip to main content

Vercel Deployment

This guide covers deploying CivStart frontends (documentation, frontend app, admin panel) to Vercel.

Documentation Site Deployment​

Option 1: Deploy via Vercel Dashboard​

  1. Import Project

    • Go to https://vercel.com/new
    • Select "Add New Project"
    • Import the CivStart repository
    • Select the apps/docs directory as the root

  2. Configure Project Settings

    Project Name: civstart-docs
    Framework Preset: Other
    Root Directory: apps/docs
    Build Command: pnpm build
    Output Directory: build
    Install Command: pnpm install --filter=@civstart/docs...

  3. Deploy

    • Click "Deploy"
    • Wait for the build to complete
    • Note the deployment URL (e.g., civstart-docs.vercel.app)

Option 2: Deploy via Vercel CLI​

# Install Vercel CLI
npm i -g vercel

# Login to Vercel
vercel login

# Deploy from project root
cd /path/to/CivStart
vercel --cwd apps/docs

# Follow the prompts

Cloudflare DNS Configuration​

Step 1: Add DNS Record​

  1. Log in to Cloudflare dashboard
  2. Select your domain: civstart.ventures
  3. Go to DNS > Records
  4. Click "Add record"

Configure the CNAME record:

Type: CNAME
Name: docs
Target: cname.vercel-dns.com
Proxy status: Proxied (orange cloud)
TTL: Auto

Step 2: Configure Custom Domain in Vercel​

  1. Go to Vercel project settings
  2. Navigate to "Domains"
  3. Click "Add Domain"
  4. Enter: docs.civstart.ventures
  5. Vercel will verify the DNS record
  6. Once verified, SSL will be automatically configured

Step 3: Wait for SSL Provisioning​

  • SSL certificates are automatically provisioned by Vercel
  • Usually takes 30-60 seconds
  • You'll see a green checkmark when ready

Continuous Deployment​

Automatic Deployments​

Vercel automatically deploys when you push to GitHub:

  • Production: Pushes to main branch
  • Preview: Pushes to any branch generates preview URL

Manual Deployments​

From the Vercel dashboard:

  1. Go to your project
  2. Click "Deployments"
  3. Click "..." menu on any deployment
  4. Select "Redeploy"

Deploy via CLI​

# Deploy to production
vercel --prod --cwd apps/docs

# Deploy preview
vercel --cwd apps/docs

Build Configuration​

The apps/docs/vercel.json file contains:

{
  "buildCommand": "pnpm build",
  "outputDirectory": "build",
  "installCommand": "pnpm install --filter=@civstart/docs...",
  "framework": null,
  "public": false
}

Troubleshooting​

Build Failures​

If the build fails:

  1. Check build logs in Vercel dashboard
  2. Test build locally: 
    pnpm --filter=@civstart/docs build
  3. Common issues:
    • Broken links - Check docusaurus.config.ts
    • Missing dependencies - Check package.json
    • Invalid markdown - Check .md files

DNS Not Resolving​

  1. Wait 5-10 minutes for DNS propagation
  2. Check DNS with: 
    dig docs.civstart.ventures
    nslookup docs.civstart.ventures
  3. Verify Cloudflare DNS record is correct
  4. Ensure "Proxied" status is enabled (orange cloud)

SSL Certificate Issues​

  1. Verify domain is added in Vercel
  2. Check Cloudflare SSL/TLS mode is "Full" or "Full (strict)"
  3. Wait up to 24 hours for certificate provisioning
  4. Contact Vercel support if issues persist

Quick Reference​

# Local development
pnpm --filter=@civstart/docs dev

# Build locally
pnpm --filter=@civstart/docs build

# Serve built site
pnpm --filter=@civstart/docs serve

# Deploy to production
vercel --prod --cwd apps/docs