Agility CMS

Developer

Demo Site: Deployment Configuration

This guide covers deployment configuration for the Demo Site, including environment variables, build process, and deployment platforms.

Environment Variables

Required Variables

Optional Variables

Build Process

Pre-build Step

Critical: Always run pre-build before production build:

This step:

  • Rebuilds redirect cache from bloom filters
  • Generates static redirect data
  • Prepares build-time data

Build Command

Build process:

  1. Runs pre-build step (if not already run)
  2. Generates static pages for all locales
  3. Builds API routes
  4. Optimizes assets
  5. Generates sitemap and robots.txt

Build Output

Deployment Platforms

Vercel

Configuration:

  • Framework: Next.js
  • Build Command: npm run prebuild && npm run build
  • Output Directory: .next
  • Install Command: npm install

Environment Variables:

  • Add all required variables in Vercel dashboard
  • Set production and preview environment variables separately

Webhook Configuration:

  • Add webhook URL: https://your-site.vercel.app/api/revalidate
  • Set security key header: x-agility-security-key

Netlify

Configuration:

  • Build Command: npm run prebuild && npm run build
  • Publish Directory: .next
  • Node Version: 20.x

Build Hooks:

  • Configure build hook URL in BUILD_HOOK_URL
  • Used for redirect cache rebuilds

Other Platforms

General Requirements:

  • Node.js 20.x or later
  • Support for Next.js App Router
  • Environment variable configuration
  • Webhook endpoint support

Webhook Setup

Agility CMS Webhook Configuration

  1. Navigate to Settings → Webhooks
  2. Add webhook:
    • URL: https://your-site.com/api/revalidate
    • Events: Content Published, Page Published
    • Security Key: Use AGILITY_SECURITY_KEY
  3. Test webhook

Webhook Security

Validate webhook requests:

Cache Strategy

Production Caching

  • Cache Duration: 60 seconds default
  • Cache Tags: Tag-based invalidation
  • Revalidation: Webhook-triggered
  • Static Generation: Pre-render at build time

Preview Mode

  • Preview mode bypasses cache
  • Uses preview API key
  • Shows draft content

Monitoring

Health Checks

Monitor API endpoints:

  • /api/revalidate - Webhook health
  • /api/preview - Preview functionality
  • Main site - Uptime monitoring

Error Tracking

  • Monitor API errors
  • Track cache misses
  • Log webhook failures

Troubleshooting

Build Failures

Issue: Build fails during pre-build

Solutions:

  • Check environment variables are set
  • Verify API keys are valid
  • Check network connectivity to Agility API

Cache Not Invalidating

Issue: Content not updating after publish

Solutions:

  • Verify webhook is configured correctly
  • Check webhook security key matches
  • Verify cache tags are correct
  • Check webhook logs for errors

Preview Not Working

Issue: Preview mode not showing draft content

Solutions:

  • Verify preview API key is set
  • Check preview endpoint is accessible
  • Verify draft mode is enabled
  • Check preview key validation

Back to: Demo Site Overview