Skip to main content
This guide covers deploying DocuSphere to a production environment. You will configure your environment variables, build the Next.js app, deploy the Convex backend, and host the frontend on a platform of your choice.

​
Prerequisites

Before deploying, make sure you have:
  • Node.js 18 or later and npm installed
  • A Convex account with a project created
  • A Clerk account with an application created
  • A Liveblocks account with a project created

​
Environment variables

DocuSphere requires seven environment variables. Set these in your hosting platform’s dashboard (or in a .env.local file if running locally).
Variables prefixed with NEXT_PUBLIC_ are embedded into the browser bundle at build time and are visible to anyone who inspects your site. Never put secret values — such as CLERK_SECRET_KEY — in a NEXT_PUBLIC_ variable.
VariableDescription
CONVEX_DEPLOYMENTYour Convex deployment identifier. Use prod:your-deployment for production deployments.
NEXT_PUBLIC_CONVEX_URLThe HTTPS URL of your Convex deployment (e.g. https://your-deployment.convex.cloud). Exposed to the browser.
NEXT_PUBLIC_CONVEX_SITE_URLThe site URL of your Convex deployment (e.g. https://your-deployment.convex.site). Exposed to the browser.
CLERK_JWT_ISSUER_DOMAINYour Clerk JWT issuer domain, used by Convex to verify authentication tokens (e.g. https://your-domain.clerk.accounts.dev). Keep this server-side.
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEYYour Clerk publishable key (starts with pk_). Exposed to the browser — this is safe.
CLERK_SECRET_KEYYour Clerk secret key (starts with sk_). Never expose this to the browser.
NEXT_PUBLIC_LIVEBLOCKS_SECRET_KEYYour Liveblocks secret key (starts with sk_dev_ or sk_prod_). Read only in a server-side API route — not exposed to the browser despite the NEXT_PUBLIC_ prefix in its name.

​
Deploy the Convex backend

Before building the Next.js app, deploy your Convex functions and schema to the production Convex environment: 
npx convex deploy
This command pushes your schema and all Convex functions to your production deployment. Run it from the root of the repository with your production environment variables set.
Make sure CONVEX_DEPLOYMENT points to your production deployment (e.g. prod:your-deployment) before running npx convex deploy.

​
Build and start the Next.js app

Once the Convex backend is deployed, build the Next.js app: 
npm run build
Then start the production server: 
npm run start
The app listens on port 3000 by default.

​
Deploying to Vercel

Vercel is the recommended hosting platform for DocuSphere because it is designed for Next.js and supports serverless deployment out of the box.
1

Connect your repository

Go to vercel.com, create a new project, and import your DocuSphere repository from GitHub.
2

Add environment variables

In the Vercel project settings, navigate to Settings → Environment Variables and add all seven variables listed in the table above. Set each variable for the Production environment (and Preview if needed).
3

Deploy

Trigger a deployment from the Vercel dashboard or by pushing to your main branch. Vercel runs npm run build automatically and serves the output.
4

Verify

Open your deployed URL, sign in with Clerk, and create a document to confirm everything is working end to end.
You must run npx convex deploy separately before or after each Vercel deployment when you make changes to your Convex schema or functions. Vercel does not run Convex deployment as part of its build step unless you add it to the build command in your project settings.

Build docs developers (and LLMs) love

Get started for freeTalk to us