Deploying Next.js + Convex AI Apps

Building an AI app is one thing — getting it running reliably in production is another. Deployment is where environment variables go missing, OAuth callbacks break, and your database silently points at the wrong instance. This guide walks through every step of deploying a Next.js + Convex AI app to Coolify, with enough detail that nothing falls through the cracks.

If you're still building your app, start with building your first AI agent in TypeScript and come back here when you're ready to ship.

Prerequisites

• Next.js 16 app with Convex
• Coolify project or another Node-capable host
• Convex account
• Claude API key from Anthropic
• A custom domain (optional)

What you'll build

You'll deploy a full AI app with:

• Next.js 16 frontend running as a Node service
• Convex backend deployed to production
• Proper environment variables
• Git push or webhook-triggered deployment
• Custom domain setup through Cloudflare DNS
• Monitoring and observability

1) Prepare your repo

Make sure your project builds locally before attempting a production deploy:

pnpm install
pnpm build

Fix any TypeScript errors or build warnings. A clean local build is the best predictor of a successful deploy.

Commit all changes to GitHub (using the amirbrooks account):

git add -A
git commit -m "chore: prepare for production deploy"
git push origin main

2) Set up Convex production

Your Convex development instance and production instance are separate. You need to explicitly deploy to production.

In your repo, run:

npx convex deploy

This creates a production deployment. Note the production URL, which looks like:

https://your-project.convex.cloud

Important: Your production Convex URL is different from your development URL. Double-check you're using the right one in your environment variables.

You can verify the deployment in the Convex dashboard:

1. Open your project in the Convex dashboard
2. Switch to the "Production" deployment
3. Check that your schema and functions are deployed
4. Test a query in the built-in console

3) Environment variable setup (detailed)

This is where most deployment failures happen. Here's every variable you need and where to find it:

Generate your AUTH_SECRET now if you haven't:

openssl rand -base64 32

For the auth setup details, see Convex Auth for AI Apps.

4) Configure Coolify project

In Coolify:

1. Click Add New → Project
2. Import your GitHub repo
3. Coolify auto-detects Next.js — confirm the framework preset
4. Configure build settings:
   • Build command: pnpm build
   • Output directory: .next
   • Install command: pnpm install
   • Root directory: . (unless you're in a monorepo)

Add environment variables in Coolify

Go to Settings → Environment Variables and add every variable from the table above.

Critical: keep production and staging variables separate. Staging deploys need their own Convex URL pointing to a development instance; do not let staging hit the production database.

# Production environment
CONVEX_URL=https://your-project.convex.cloud
ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY

# Staging environment (different Convex instance!)
CONVEX_URL=https://your-project-dev.convex.cloud
ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY

For the broader tooling, hosting, and deployment landscape, see Best AI Dev Tools 2026.

5) Deploy

Click Deploy in Coolify or push a commit to trigger a build.

Once deployed, test the live app and ensure:

• Auth callbacks return successfully
• Agent API routes respond
• Convex mutations work in production
• No console errors in the browser

# Quick smoke test from the command line
curl -s https://your-app.example.com/api/health | jq

6) Set up custom domain

In Coolify → Domains:

1. Add your domain (e.g., ai.amirbrooks.com.au)
2. Update DNS records in Cloudflare:

CNAME ai -> your Coolify proxy target

3. Wait for SSL to provision (usually under 5 minutes)
4. Verify by visiting https://ai.amirbrooks.com.au

If you're using a root domain (amirbrooks.com.au instead of a subdomain), you'll need an A record instead:

A @ your server IPv4 address
AAAA @ your server IPv6 address, if available

7) Configure OAuth callbacks for production

Update GitHub and Google OAuth apps to use the production domain:

https://ai.amirbrooks.com.au/api/auth/callback/github
https://ai.amirbrooks.com.au/api/auth/callback/google

Tip: Keep your localhost callback URLs too — you can add multiple redirect URIs. This way local development continues to work.

8) Deployment flow

For simple production apps, keep the release flow boring:

1. Run typecheck, lint, and build locally or in CI.
2. Deploy Convex first when schema or function changes are included.
3. Push the selected commit to the branch Coolify watches, or trigger the Coolify webhook for that commit.
4. Confirm the running container reports the expected release.
5. Smoke-test the public URL and key auth/API routes.

The important ordering is Convex first, web app second. That keeps schema changes live before the frontend expects them.

9) Verify Convex connection

Test a simple query from production to confirm the backend is connected:

import { ConvexHttpClient } from "convex/browser";
import { api } from "@/convex/_generated/api";

const client = new ConvexHttpClient(process.env.CONVEX_URL!);

export async function GET() {
  const health = await client.query(api.health.check, {});
  return Response.json({ ok: true, data: health });
}

10) Monitoring after deploy

A deployed app isn't a finished app. Set up monitoring from day one.

App monitoring

Use the monitoring stack that fits your app. For this kind of product, start with:

• /api/health release checks
• server logs from the running container
• Sentry or another error tracker
• Cloudflare analytics for edge traffic and DNS/proxy health

Convex Dashboard

The Convex dashboard shows:

• Function execution logs (queries, mutations, actions)
• Error rates and stack traces
• Database storage usage
• Real-time event stream

Check it daily for the first week after launch. Most issues surface within 48 hours.

11) Common deployment errors and fixes

12) Production checklist

Before calling your app "production-ready," verify everything on this list:

• All environment variables set in Coolify for production and staging
• Convex deployed to production (npx convex deploy)
• OAuth callback URLs updated to production domain
• Custom domain configured and SSL provisioned
• AUTH_SECRET is unique per environment (don't share between dev and prod)
• Anthropic billing enabled (free tier has strict limits)
• Error pages configured (404, 500, auth errors)
• Rate limiting enabled on agent API routes
• App monitoring enabled
• Convex dashboard bookmarked and checked
• GitHub Actions pipeline passing
• Staging deploys use a separate Convex instance
• CORS headers configured if agents call from external origins

This is the same stack recommended in the Next.js + Convex AI app stack guide.

13) Troubleshooting tips

• Build fails on Coolify: Ensure pnpm-lock.yaml is committed. Run pnpm install locally and push the lockfile.
• Auth callbacks fail: Update OAuth callback URLs to match the live domain exactly.
• Convex errors: Run npx convex deploy again if schema mismatches.
• Missing env vars: Confirm variables are set for the right environments (Production vs Preview vs Development).
• First request latency: If the container was recently rebuilt or restarted, the first request may be slower. Check container logs and cache warm-up behavior before changing infrastructure.

Final thoughts

Deployment is where AI apps break most often. With Coolify + Convex, you get fast iteration, reliable hosting, and scalable backends that are easy to maintain. The CI/CD pipeline ensures your Convex schema and Next.js frontend stay in sync, and the monitoring setup catches issues before your users do. Once the pipeline is stable, you can focus on building better agents. The AI Product Building course covers the full deployment workflow and beyond. If you want the full framework for going from idea to deployed AI product, the AI Product Building course covers the entire process.