Copy page

Guides

Production Deployment Checklist

This guide walks you through configuring the Open Paws API Gateway for production deployment in Zuplo.

Prerequisites

Before deploying to production, ensure you have:

• Zuplo account with production environment access
• All backend service URLs and credentials ready
• Frontend application URLs for CORS configuration
• Production identity provider configured (to replace demo Auth0)

Environment Variables Overview

The API Gateway requires environment variables across several categories. The table below summarizes all required variables:

Variable	Description	Type	Required
OPENAI_API_KEY	Chat, content generation, intent detection, embeddings	Secret	Yes
SUPABASE_URL	Supabase database URL for search endpoints	URL	Yes
SUPABASE_PUBLISHABLE_KEY	Supabase public/publishable key	Config	Yes
N8N_BASE_URL	n8n webhook base URL for OSINT, legal, tracking	URL	Yes
N8N_WEBHOOK_KEY	n8n webhook authentication key	Secret	Yes
STRIPE_SECRET_KEY	Stripe API secret key for billing	Secret	Yes
STRIPE_WEBHOOK_SECRET	Stripe webhook signature verification	Secret	Yes
STRIPE_STANDARD_PRICE_ID	Stripe Price ID for standard plan	Config	Yes
STRIPE_METER_EVENT_NAME	Stripe Billing Meter event name	Config	Yes
STRIPE_PORTAL_RETURN_URL	Billing portal redirect URL	Config	Yes
DEVELOPER_API_KEY	Zuplo Developer API key for consumer management	Secret	Yes
DEVELOPER_API_ACCOUNT	Zuplo account slug	Config	Yes
DEVELOPER_API_BUCKET	API key bucket name	Config	Yes
CLERK_WEBHOOK_SECRET	Clerk webhook signature verification	Secret	Yes
DATADOG_API_KEY	DataDog API key for logging and metrics	Secret	No
ENVIRONMENT	Environment name (production, staging)	Config	Yes
LOG_LEVEL	Log level override (error, warn, info)	Config	No

Type Legend:

• Config: Plain configuration value, not sensitive
• URL: Backend service endpoint, not sensitive
• Secret: Contains API keys or sensitive data — mark as secret in Zuplo

Step-by-Step Configuration

Step 1: Access Zuplo Portal

1. Log in to your Zuplo account
2. Navigate to your project
3. Go to Settings → Environment Variables
4. Select your production environment

Step 2: Configure Backend Services

Core Services

Variable	Mark As	Purpose
OPENAI_API_KEY	Secret	Chat, content generation, intent detection, semantic search embeddings
SUPABASE_URL	Configuration	Supabase database for search endpoints
SUPABASE_PUBLISHABLE_KEY	Configuration	Supabase public key
N8N_BASE_URL	Configuration	n8n webhook base URL (e.g., https://automation.openpaws.ai/webhook)
N8N_WEBHOOK_KEY	Secret	n8n webhook authentication key

Stripe Billing

Variable	Mark As	Purpose
STRIPE_SECRET_KEY	Secret	Stripe API calls
STRIPE_WEBHOOK_SECRET	Secret	Webhook signature verification
STRIPE_STANDARD_PRICE_ID	Configuration	Checkout session price ID
STRIPE_METER_EVENT_NAME	Configuration	Billing meter event name (e.g., api_credits)
STRIPE_PORTAL_RETURN_URL	Configuration	Billing portal redirect URL

API Key Management (Zuplo Developer API)

Variable	Mark As	Purpose
DEVELOPER_API_KEY	Secret	Manage API consumers
DEVELOPER_API_ACCOUNT	Configuration	Zuplo account slug
DEVELOPER_API_BUCKET	Configuration	API key bucket name

Webhooks

Variable	Mark As	Purpose
CLERK_WEBHOOK_SECRET	Secret	Clerk webhook signature verification

Observability (optional)

Variable	Mark As	Purpose
DATADOG_API_KEY	Secret	DataDog logging and metrics
ENVIRONMENT	Configuration	Environment name (production, staging)
LOG_LEVEL	Configuration	Log level override (error, warn, info)

Step 3: Configure CORS

CORS is configured in config/policies.json under the frontend-app policy. Update the allowed origins for your deployment:

• https://app.openpaws.ai — Production frontend
• https://www.app.openpaws.ai — www subdomain
• http://localhost:5173 — Local development

Important:

• Do NOT include trailing slashes
• Do NOT use wildcards (*) in production
• Include all domains that will make API requests

Step 3: Configure Developer Portal Authentication (Auth0)

The developer portal uses Auth0 for user authentication. This enables users to sign in and access their API keys.

Prerequisites

Before configuring Auth0:

• Create an Auth0 account or use your existing Auth0 tenant
• Note your Auth0 tenant domain (e.g., your-company.us.auth0.com)

Auth0 Application Setup

1. Navigate to Auth0 Dashboard → Applications → Create Application
2. Select Single Page Application as the application type
3. Name your application (e.g., "Open Paws Developer Portal")
4. Configure the following URLs in your application settings:

Allowed Callback URLs:

Code
https://your-portal-domain.com/oauth/callback, http://localhost:9000/oauth/callback

Allowed Logout URLs:

Code
https://your-portal-domain.com, http://localhost:9000, http://localhost:9100

Allowed Web Origins:

Code
https://your-portal-domain.com, http://localhost:9000, http://localhost:9100

5. Copy the Domain and Client ID values from the application settings

Auth0 API Setup (Optional but Recommended)

Creating an API in Auth0 allows you to validate access tokens and control API permissions:

1. Navigate to Auth0 Dashboard → APIs → Create API
2. Set Name: "Open Paws API"
3. Set Identifier (audience): https://api.your-domain.com (use your actual API domain)
4. Copy the Identifier value for the ZUPLO_PUBLIC_AUTH0_AUDIENCE variable

Zuplo Environment Variables

Configure the following variables in Zuplo portal (Settings → Environment Variables):

Variable	Mark As	Example
ZUPLO_PUBLIC_AUTH0_DOMAIN	Configuration	your-tenant.us.auth0.com
ZUPLO_PUBLIC_AUTH0_CLIENT_ID	Configuration	abc123def456ghi789
ZUPLO_PUBLIC_AUTH0_AUDIENCE	Configuration	https://api.your-domain.com

Important Notes:

• These variables are prefixed with ZUPLO_PUBLIC_ because they are accessible to client-side code in the developer portal
• They are not secrets and will be visible in the browser - this is expected behavior for OAuth 2.0 SPA clients
• The audience should match the API identifier you created in Auth0

Verification

After configuring Auth0:

1. Deploy to a preview environment
2. Navigate to the developer portal
3. Click the Sign In button
4. Verify the Auth0 login page appears with your tenant branding
5. Complete the login process
6. Verify you are redirected back to the portal
7. Check that the API Keys section is accessible after login

Step 4: Verify Configuration

After adding all variables:

1. Count variables: Verify all environment variables from the table above are configured
2. Check secrets: Ensure API keys and webhook secrets are marked as secrets (masked in UI)
3. Verify names: Variable names are case-sensitive — double-check for typos
4. Preview environment: Use Zuplo's preview to test before deploying to production

Testing

Pre-Deployment Testing

Before deploying to production:

• Test each route category in preview/staging environment
• Verify authentication policies are active on all routes
• Confirm rate limiting is working as expected
• Test CORS with actual frontend domains

Post-Deployment Verification

After deploying, test sample requests to each service category:

Health Check (no auth required):

Code
curl https://api.openpaws.ai/health

Search:

Code
curl -X POST https://api.openpaws.ai/v1/search/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "factory farming", "search_type": "text", "limit": 5}'

Content Generation:

Code
curl -X POST https://api.openpaws.ai/v1/content/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"topic": "cage-free egg legislation"}'

Chat:

Code
curl -X POST https://api.openpaws.ai/v1/chat/message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are the most effective advocacy strategies?"}'

OSINT (streaming response):

Code
curl -X POST https://api.openpaws.ai/v1/osint/personal-profile \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"firstName": "Jane", "lastName": "Doe", "companyName": "Acme Corp"}'

Verify error responses:

• 401 Unauthorized - Missing or invalid API key
• 429 Too Many Requests - Rate limit exceeded
• 400 Bad Request - Invalid request body

Developer Portal Authentication Testing

Local Testing

1. Configure Auth0 variables in docs/.env (copy from docs/.env.example)
2. Run npm run dev in the docs directory
3. Navigate to http://localhost:9000
4. Click Sign In and test login with an Auth0 test user
5. Verify the API Keys section appears after login

Preview Environment Testing

1. Deploy to Zuplo preview environment
2. Configure Auth0 callback URLs to include the preview domain
3. Test login flow with your Auth0 tenant
4. Verify correlation between Auth0 email and API Key consumers

Production Testing

After production deployment:

1. Test with a real user account
2. Verify Auth0 branding matches your organization
3. Test API Key generation for new users
4. Verify logout flow returns to the correct page
5. Confirm that only production domains are in Auth0 callback URLs (no localhost)

Security Checklist

Before going live, verify:

• All sensitive URLs marked as Secrets in Zuplo
• ALLOWED_ORIGINS contains only production domains (no wildcards)
• Authentication policy active on all routes (check routes.oas.json)
• Rate limiting configured appropriately (check policies.json)
• Auth0 environment variables configured with production tenant credentials
• Auth0 callback URLs configured for production domain only (no localhost in production)
• API Key Service configured for consumer management
• No test/development URLs in production environment

Troubleshooting

Common Issues

502 Bad Gateway

• Backend service URL is incorrect
• Backend service is down or unreachable
• Network/firewall blocking Zuplo → backend connection

Solution: Verify the backend URL is correct and the service is accessible.

CORS Errors

• ALLOWED_ORIGINS misconfigured
• Frontend domain missing from allowed list
• Trailing slash in origin URL

Solution: Check ALLOWED_ORIGINS includes your frontend domain exactly (no trailing slash).

401 Unauthorized

• Authentication policy not configured
• API keys invalid or expired
• Token not included in request

Solution: Verify authentication is properly configured in routes.oas.json.

Environment Variable Not Found

• Variable name has a typo
• Variable not set in the correct environment
• Case sensitivity issue

Solution: Double-check variable names match exactly (case-sensitive).

Rate Limiting Issues

• Rate limits too aggressive
• Consumer not properly identified

Solution: Review rate limit configuration in policies.json.

Rollback Plan

If deployment issues occur:

1. Quick rollback: Use Zuplo's deployment history to revert to previous version
2. Environment backup: Keep a backup of working environment variables before making changes
3. Staged rollout: Deploy to staging first, verify, then promote to production

Backing Up Environment Variables

Before making changes, export your current configuration:

1. Go to Settings → Environment Variables
2. Document all current values (screenshot or copy to secure location)
3. Note which variables are marked as secrets

Using Deployment History

1. Go to Deployments in Zuplo
2. Find the last known working deployment
3. Click Rollback to restore that version

CI/CD Pipeline Setup

The repository includes GitHub Actions workflows for automated testing and deployment. Follow these steps to configure CI/CD:

Prerequisites

Before enabling CI/CD, complete these steps:

• Disconnect Zuplo's built-in GitHub integration to prevent double deployments
• Generate a Zuplo API key for GitHub Actions
• Configure GitHub repository secrets and environments

Step 1: Disconnect Built-in Zuplo Integration

1. Navigate to Zuplo portal → Settings → Source Control
2. Click Disconnect to disable automatic deployments
3. This ensures only your custom GitHub Actions control deployments

Step 2: Generate Zuplo API Key

1. In Zuplo portal, go to Settings → API Keys
2. Click New Key and name it "GitHub Actions CI/CD"
3. Copy the generated API key (you won't be able to see it again)

Step 3: Configure GitHub Secrets

1. In your GitHub repository, go to Settings → Secrets and variables → Actions
2. Click New repository secret
3. Configure the following secret:

Secret Name	Value
ZUPLO_API_KEY	The API key generated in Step 2

Step 4: Configure GitHub Branch Protection

1. Go to repository Settings → Branches
2. Click Add branch protection rule
3. Set Branch name pattern to main
4. Enable the following options:
   • Require a pull request before merging
   • Require status checks to pass before merging
     • Add required status check: Deploy Preview & Run Tests
   • Require branches to be up to date before merging
   • Do not allow bypassing the above settings (recommended)
5. Click Create or Save changes

Step 5: Configure Production Environment

1. Go to repository Settings → Environments
2. Click New environment
3. Name it production
4. Click Configure environment
5. Enable Required reviewers and add team members who can approve production deployments
6. Optionally enable Wait timer (e.g., 5 minutes) for additional safety
7. Click Save protection rules

Workflow Overview

The CI/CD pipeline includes two workflows:

PR Preview Workflow (.github/workflows/pr-preview.yml)

• Trigger: Pull request events (opened, synchronize, reopened, closed)
• Actions:
  • Deploys to Zuplo preview environment
  • Runs full test suite (auth, validation, policies, routes, integration)
  • Posts deployment URL as PR comment
  • Cleans up preview environment when PR is closed

Production Deploy Workflow (.github/workflows/production-deploy.yml)

• Trigger: Push to main branch
• Stages:
  1. Deploy to Staging: Creates staging deployment
  2. Test Staging: Runs full test suite against staging
  3. Deploy to Production: Requires manual approval, then deploys to production

Deployment Flow

Code
Pull Request Created
       ↓
Deploy to Preview Environment
       ↓
Run All Test Suites
       ↓
[Pass] → Enable Merge Button
[Fail] → Block Merge, Show Errors
       ↓
PR Merged to main
       ↓
Deploy to Staging
       ↓
Run All Tests on Staging
       ↓
Request Manual Approval
       ↓
[Approved] → Deploy to Production

Troubleshooting CI/CD

Workflow not triggering:

• Verify workflows are in .github/workflows/ directory
• Check that branch names match trigger conditions
• Ensure repository has Actions enabled

Deployment failing:

• Verify ZUPLO_API_KEY secret is configured correctly
• Check that API key has deployment permissions
• Review workflow logs in Actions tab

Tests failing:

• Review test output in workflow logs
• Ensure all environment variables are configured
• Check that backend services are accessible

Manual approval not appearing:

• Verify production environment exists in repository settings
• Check that required reviewers are configured
• Ensure workflow uses environment: production

Rollback via CI/CD

To rollback a production deployment:

1. Go to Actions tab in GitHub
2. Find the last successful production deployment
3. Click Re-run all jobs to redeploy that version

Alternatively, use Zuplo's deployment history directly in the portal.

Next Steps

After successful deployment:

1. Verify DataDog Integration: Check that logs and metrics are flowing to DataDog

   • Navigate to DataDog Logs and search for service:api-gateway
   • Check DataDog Metrics for zuplo.request.latency metrics
   • See Observability Guide for detailed setup verification

2. Set Up DataDog Dashboards: Create monitoring dashboards for:

   • Request latency by endpoint and backend service
   • Error rates (4xx, 5xx) by route
   • Request volume trends
   • Backend service health

3. Configure Alerts: Set up DataDog monitors for:

   • High error rates (> 5% 5xx responses)
   • Elevated latency (p95 > 2s)
   • Backend service failures

4. Test Correlation ID Tracing: Make test requests and trace them across services

   • Check for x-correlation-id header in responses
   • Search DataDog logs by correlationId to trace requests

5. Review Log Levels: For production, ensure LOG_LEVEL is set to error or warn to reduce costs

   • Use info level only in staging/preview environments

6. Review API analytics for performance insights

7. Document any custom configurations for your team