Skip to main content
This page documents every environment variable DocuSphere needs to run. You set these in a .env.local file at the project root for local development, or in your hosting platform’s environment settings for production. All seven variables are required — DocuSphere will fail to start or will error at runtime if any are missing.

​
Variables

​
CONVEX_DEPLOYMENT
string
required
Your Convex deployment identifier. Use dev:your-deployment-name for local development or prod:your-deployment-name for production. Found in your Convex dashboard under the deployment’s settings. This is read by the Convex CLI and is not exposed to the browser.
​
NEXT_PUBLIC_CONVEX_URL
string
required
The HTTPS URL of your Convex deployment, for example https://happy-otter-123.convex.cloud. The Convex React client uses this URL to connect from the browser for real-time queries and mutations. Found in your Convex dashboard.
​
NEXT_PUBLIC_CONVEX_SITE_URL
string
required
The site URL of your Convex deployment, for example https://happy-otter-123.convex.site. Used when making HTTP action requests to Convex. Found in your Convex dashboard alongside NEXT_PUBLIC_CONVEX_URL.
​
CLERK_JWT_ISSUER_DOMAIN
string
required
Your Clerk JWT issuer domain, for example https://your-app.clerk.accounts.dev. Convex uses this to verify JWT tokens issued by Clerk on the server side. Found in your Clerk dashboard under JWT Templates or the Frontend API settings.
​
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
string
required
Your Clerk publishable key. Starts with pk_test_ for development instances or pk_live_ for production instances. Used by the Clerk React SDK to initialize the sign-in UI and manage sessions in the browser. Safe to include in client-side code.
​
CLERK_SECRET_KEY
string
required
Your Clerk secret key. Starts with sk_test_ for development or sk_live_ for production. Used server-side (in Next.js API routes and server components) to authenticate requests. Never expose this value in browser code or commit it to version control.
​
NEXT_PUBLIC_LIVEBLOCKS_SECRET_KEY
string
required
Your Liveblocks secret key. Starts with sk_dev_ for development or sk_prod_ for production. Used server-side in the /api/liveblocks-auth route to issue Liveblocks session tokens. Despite the NEXT_PUBLIC_ prefix in the variable name, this key is only read in a server-side API route and is never sent to the browser. Never commit this value to version control.

​
Example .env.local

Create a .env.local file in the root of your project and populate it with your actual credentials: 
# Convex
CONVEX_DEPLOYMENT=dev:your-convex-deployment
NEXT_PUBLIC_CONVEX_URL=https://your-convex-url.convex.cloud
NEXT_PUBLIC_CONVEX_SITE_URL=https://your-convex-url.convex.site

# Clerk (Authentication)
CLERK_JWT_ISSUER_DOMAIN=https://your-app.clerk.accounts.dev
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_your_clerk_publishable_key
CLERK_SECRET_KEY=sk_test_your_clerk_secret_key

# Liveblocks (Collaboration)
NEXT_PUBLIC_LIVEBLOCKS_SECRET_KEY=sk_dev_your_liveblocks_secret_key
Replace each placeholder with the real value from your Convex, Clerk, and Liveblocks dashboards.
Never commit CLERK_SECRET_KEY or NEXT_PUBLIC_LIVEBLOCKS_SECRET_KEY to version control. Add .env.local to your .gitignore file to prevent accidental exposure of these secrets. Note that NEXT_PUBLIC_LIVEBLOCKS_SECRET_KEY has a NEXT_PUBLIC_ prefix in its name but is only consumed server-side — it is not bundled into the browser.
Variables prefixed with NEXT_PUBLIC_ are bundled into the browser JavaScript that Next.js sends to users. Only use this prefix for values that are safe to make public, such as publishable keys and service URLs.

Build docs developers (and LLMs) love

Get started for freeTalk to us