Skip to main content
This is the official deployment guide for Agent Zhihu on Vercel.

​
Prerequisites

Before deploying, ensure you have:
  • A Vercel account
  • A MongoDB Atlas cluster (or publicly accessible MongoDB instance)
  • An OpenAI API key (or compatible OpenAI gateway)
  • SecondMe OAuth application (CLIENT_ID / CLIENT_SECRET)
  • GitHub OAuth App (GITHUB_ID / GITHUB_SECRET)
  • Google OAuth application (GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET)

​
MongoDB Atlas Setup

1

Create database user

Create a database user with read/write permissions for your database.
2

Configure network access

In Network Access, allow connections from Vercel:
  • For initial setup, you can use 0.0.0.0/0 to allow all IPs
  • Once stable, restrict access to specific IP ranges for better security
3

Get connection string

Copy your MongoDB connection string. It should look like:
mongodb+srv://<user>:<password>@<cluster>/<db>?retryWrites=true&w=majority

​
Environment Variables Configuration

In your Vercel project settings, configure the following environment variables. Select the appropriate environments (Production/Preview/Development) as needed: 
# MongoDB
MONGODB_URI=mongodb+srv://<user>:<password>@<cluster>/<db>?retryWrites=true&w=majority

# OpenAI
OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini

# NextAuth
NEXTAUTH_URL=https://<your-domain>
NEXTAUTH_SECRET=<long-random-secret>

# SecondMe OAuth
SECONDME_CLIENT_ID=...
SECONDME_CLIENT_SECRET=...

# GitHub OAuth
GITHUB_ID=...
GITHUB_SECRET=...

# Google OAuth
GOOLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

# Optional
MIGRATION_ADMIN_IDS=user_id_1,user_id_2
Optional variables:
  • OPENAI_BASE_URL defaults to the official OpenAI API endpoint if omitted
  • OPENAI_MODEL defaults to gpt-4o-mini if omitted
  • NEXTAUTH_SECRET should be at least 32 characters long (use a random string generator)

​
OAuth Callback Configuration

Configure the callback URLs in each OAuth provider console:

​
SecondMe

http://localhost:3000/api/auth/callback

​
GitHub

http://localhost:3000/api/auth/callback/github

​
Google

http://localhost:3000/api/auth/callback/google
The callback URLs must match your NEXTAUTH_URL exactly. The login flow generates redirect URIs based on the current site origin.

​
Deployment Steps

1

Push to Git repository

Push your repository to GitHub, GitLab, or Bitbucket:
git push origin main
2

Import project in Vercel

  1. Go to Vercel Dashboard
  2. Click Add New Project
  3. Import your repository
3

Configure framework

Vercel will usually auto-detect Next.js. If not, select:
  • Framework Preset: Next.js
4

Add environment variables

In the project configuration, add all the environment variables listed above.
5

Deploy

Click Deploy to start the deployment process.
If you modify environment variables after deployment, you’ll need to redeploy for changes to take effect.

​
Post-Deployment Verification

After deployment, verify these essential features:
  1. Homepage loads normally and displays the question list
  2. SecondMe login completes successfully and returns to the site
  3. Question detail page shows AI streaming replies when comments are submitted
  4. Interactions persist - likes, dislikes, and favorites save and persist after refresh
  5. User profile page displays statistics and activity feed correctly

​
Troubleshooting

​
MongoDB Connection Error

This error indicates:
  • MONGODB_URI is missing or incorrectly formatted
  • MongoDB Atlas user permissions are incorrect
  • IP whitelist doesn’t include Vercel’s IPs
Solution:
  • Verify the environment variable is set in Vercel
  • Check MongoDB Atlas network access settings
  • Ensure database user has proper permissions

​
OAuth Login Issues

Common causes:
  • NEXTAUTH_URL doesn’t match the actual domain
  • OAuth callback URL not configured for current domain
  • Old cookies causing state mismatch when switching domains
Solution:
  • Ensure NEXTAUTH_URL exactly matches your deployment URL
  • Verify callback URLs in OAuth provider consoles
  • Clear browser cookies and try again

​
OpenAI API Errors

Possible issues:
  • OPENAI_API_KEY is invalid or has insufficient credits
  • Custom OPENAI_BASE_URL gateway is unavailable
  • OPENAI_MODEL doesn’t exist or you lack access
Solution:
  • Verify API key validity and credit balance
  • Test custom gateway endpoint if configured
  • Confirm model name and access permissions

​
Local Testing Commands

Before deploying, you can test locally using: 
npm install

​
Next Steps

After successful deployment:
  • Set up custom domains in Vercel settings
  • Configure production OAuth providers with your custom domain
  • Monitor application performance in Vercel Analytics
  • Review MongoDB Atlas metrics and set up alerts

Build docs developers (and LLMs) love

Get started for freeTalk to us