Vercel Deployment Guide

Overview

Vercel is our hosting platform for all client projects. It provides:

• Automatic deployments from GitHub
• Free SSL certificates
• Global CDN
• Preview deployments for pull requests
• Environment variable management
• Custom domain support

Creating a New Vercel Project

Method 1: Via Vercel CLI (Recommended)

# Navigate to project directory
cd ~/PAI/Workshop/client-sites/client-name

# Initialize Vercel project
vercel --prod

# Follow prompts:
# - Set up and deploy? Yes
# - Which scope? freebeerstudio
# - Link to existing project? No
# - What's your project's name? client-name
# - In which directory is your code? ./
# - Want to modify settings? No

Result:

• Project created in Vercel dashboard
• .vercel/project.json created locally
• Initial deployment to production

Method 2: Via Vercel Dashboard

1. Go to: https://vercel.com/new
2. Select "Import Git Repository"
3. Choose GitHub organization: freebeerstudio
4. Select repository: client-name
5. Configure project:
   • Framework Preset: Next.js (or appropriate framework)
   • Root Directory: ./
   • Build Command: npm run build
   • Output Directory: .next (or appropriate)
6. Click "Deploy"

Project Configuration

Getting Project IDs

You'll need these IDs for GitHub Actions automation:

Organization ID:

# From Vercel CLI
vercel teams ls

# Output shows:
# freebeerstudio (team_1EitYv6CCRydiKfiQvChvQS0)

Project ID:

# From .vercel/project.json
cat .vercel/project.json

# Look for projectId
{
  "projectId": "prj_xxxxxxxxxxxxx",
  "orgId": "team_1EitYv6CCRydiKfiQvChvQS0"
}

Or from Vercel Dashboard:

1. Go to project settings
2. Scroll to "Project ID"
3. Copy the ID

Environment Variables

Configure different variables for each environment:

1. Go to: Project Settings → Environment Variables
2. Add variables for each environment:
   • Production
   • Preview
   • Development

Example environment variables:

NEXT_PUBLIC_APP_NAME="Client Name - Dev"
NEXT_PUBLIC_APP_URL="https://client.dev.freebeer.ai"
NEXT_PUBLIC_API_URL="https://api.example.com"

Custom Domains

Adding Domains to Vercel Project

Each client project typically has three domains:

• Development: client.dev.freebeer.ai
• Staging: client.staging.freebeer.ai
• Production: clientdomain.com

Via Vercel Dashboard

1. Go to: Project → Settings → Domains
2. Click "Add"
3. Enter domain: client.dev.freebeer.ai
4. Click "Add"
5. Repeat for staging and production domains

Via Vercel CLI

# Add development domain
npx vercel domains add client.dev.freebeer.ai

# Add staging domain
npx vercel domains add client.staging.freebeer.ai

# Add production domain (client's domain)
npx vercel domains add clientdomain.com

Domain Verification

After adding a domain, Vercel will check DNS configuration:

For subdomains (*.freebeer.ai):

• Vercel detects DNS automatically
• Usually verified within 1-5 minutes
• No additional configuration needed

For client domains:

• Client must add DNS records (see Cloudflare guide)
• Verification may take 24-48 hours
• SSL certificate provisioned automatically after verification

SSL Certificates

Vercel automatically provisions SSL certificates for all domains:

• Certificates are free and auto-renewing
• Uses Let's Encrypt
• No configuration required
• HTTPS enforced by default

Deployment Methods

1. Automatic Deployments (GitHub Integration)

When GitHub Actions is configured:

• Push to main branch → Deploy to development
• Manual workflow trigger → Deploy to staging
• Tag push (v*.*.*) → Deploy to production

2. Manual CLI Deployment

# Deploy to production
vercel --prod

# Deploy to preview (not production)
vercel

# Deploy with specific environment
vercel --prod -e NEXT_PUBLIC_ENV=production

3. Via Vercel Dashboard

1. Go to: Project → Deployments
2. Click "..." on any deployment
3. Click "Promote to Production"

Deployment Workflows

Development Environment

# Workflow: .github/workflows/dev-deploy.yml
# Trigger: Push to main branch
# Target: client.dev.freebeer.ai
# Auto-deployment: Yes

Staging Environment

# Workflow: .github/workflows/staging-deploy.yml
# Trigger: Manual workflow dispatch
# Target: client.staging.freebeer.ai
# Auto-deployment: No (manual trigger)

Production Environment

# Workflow: .github/workflows/production-deploy.yml
# Trigger: Git tag push (v*.*.*)
# Target: clientdomain.com
# Auto-deployment: Yes (when tag is pushed)

Monitoring Deployments

Vercel Dashboard

• Go to: Vercel Dashboard
• Select project
• View:
  • Deployment history
  • Build logs
  • Runtime logs
  • Analytics

Deployment Status

Build Logs

To view build logs:

1. Click on deployment
2. Click "Building" or "View Build Logs"
3. Expand sections to see detailed output

Runtime Logs

To view runtime logs:

1. Go to: Project → Logs
2. Filter by:
   • Time range
   • Deployment
   • Log level (info, warning, error)

Vercel API Authentication

Creating a Vercel Token

1. Go to: Account Settings → Tokens
2. Click "Create Token"
3. Name: "GitHub Actions - Free Beer Studio"
4. Scope: freebeerstudio
5. Expiration: No Expiration (or set custom)
6. Click "Create"

Storing Token for Automation

For local development:

# Add to ~/.zshrc
export VERCEL_TOKEN="your_token_here"

# Reload shell
source ~/.zshrc

For GitHub Actions:

1. Go to: Repository → Settings → Secrets
2. Add secret:
   • Name: VERCEL_TOKEN
   • Value: [your token]

Project Limits & Pricing

Free Tier (Hobby)

Pro Tier

Recommended Strategy

• Start with Free tier for testing
• Upgrade to Pro when:
  • You have 5+ active clients
  • Bandwidth exceeds 100 GB/month
  • You need team collaboration
• Bill clients for Pro tier costs
• Or bundle into monthly service fee

Troubleshooting

Build Failures

Common causes:

• Missing dependencies in package.json
• Build script errors
• Environment variables not set
• Node version mismatch

Solutions:

1. Check build logs for specific error
2. Verify all dependencies are listed
3. Test build locally: npm run build
4. Check environment variables are set

Domain Not Verified

Causes:

• DNS records not configured
• DNS not yet propagated
• Incorrect CNAME/A record

Solutions:

1. Verify DNS records: dig domain.com
2. Wait 24-48 hours for propagation
3. Check Cloudflare DNS settings

Deployment Not Showing Changes

Solutions:

1. Clear browser cache (Cmd+Shift+R)
2. Check deployment was successful
3. Verify correct branch was deployed
4. Check if domain is pointing to correct deployment

"Invalid Scope" Error

Cause: Token not scoped to organization

Solution:

1. Create new token
2. Select "freebeerstudio" scope
3. Update VERCEL_TOKEN secret

Best Practices

Project Organization

• One Vercel project per client
• Use consistent naming: client-name
• Link to GitHub repository
• Configure all three environments (dev, staging, prod)

Environment Variables

• Set different values for each environment
• Never commit secrets to repository
• Use NEXT_PUBLIC_* prefix for client-side variables
• Document all required variables in .env.example

Deployments

• Always test in development first
• Get client approval on staging before production
• Use semantic versioning for production tags
• Keep deployment history clean (don't promote failed builds)

Monitoring

• Check deployments regularly
• Review runtime logs for errors
• Monitor bandwidth usage
• Set up alerts for failed deployments

Quick Reference

Useful CLI Commands

# Initialize new project
vercel

# Deploy to production
vercel --prod

# List deployments
vercel ls

# Get deployment logs
vercel logs [deployment-url]

# Add domain
vercel domains add domain.com

# Remove domain
vercel domains rm domain.com

# List environment variables
vercel env ls

# Add environment variable
vercel env add VARIABLE_NAME

Important Links

• Dashboard: https://vercel.com/freebeerstudio
• Documentation: https://vercel.com/docs
• API Reference: https://vercel.com/docs/rest-api
• Status Page: https://www.vercel-status.com/