Configuration
Configure the external services needed to run ChatPDF in your own environment.
Required services
Each service below needs an account and credentials before the app will work end-to-end.
Convex
Database, generated API bindings, server functions, file storage, and background jobs. Create a project at convex.dev.
Clerk
Google and GitHub social sign-in, JWT issuance, and session management. Create an app at clerk.com.
OpenAI
Embeddings (text-embedding-3-small) and grounded answer generation. Requires an API key from platform.openai.com.
Mistral
OCR 4 extracts page text from every uploaded PDF. Requires an API key from console.mistral.ai.
PostHog
Optional. Product analytics for page views and events. Omit the env vars to disable.
Clerk JWT template
After creating a Clerk application, you must create a JWT template so Convex can verify Clerk sessions.
- In your Clerk dashboard, go to JWT Templates and create a new template.
- Name it exactly convex — Convex looks for this template by name.
- Set the audience claim to your Convex deployment URL (the value of NEXT_PUBLIC_CONVEX_URL).
- Copy the issuer URL from the template and set it as CLERK_JWT_ISSUER_DOMAIN.
Template name must be convex
convex exactly. Any other name will cause authentication failures at the Convex backend, even if Clerk sign-in itself works.Environment file
Copy the example file, then fill in deployment-specific values. Every variable is documented on the Environment variables reference page.
cp .env.example .env.localKeep your URLs aligned
URL mismatch is the most common setup failure
SITE_URL, NEXT_PUBLIC_SITE_URL, the Convex site URL, and Clerk's allowed callback URLs must all point to the same origin. A mismatch is the most common reason local sign-in works while production sign-in fails — or OAuth redirects land on an error page.