Detailed instructions for configuring essential environment variables, including database, Google OAuth, and OpenAI API keys.
Environment variables are fundamental to configuring AI Docs, providing a secure and flexible way to manage sensitive credentials and adapt the application to various deployment environments. They are essential for both local development and production deployments, allowing you to inject configuration settings without hardcoding them into the codebase.
AI Docs relies heavily on environment variables for critical configurations, including database connections, authentication secrets, API keys for AI services, and integration details for external platforms like GitHub and Qdrant. This approach ensures that sensitive information is kept out of your codebase and can be easily changed across different environments (development, staging, production).
To get AI Docs running locally, you'll need to configure a .env file with the necessary environment variables.
.env FileStart by copying the provided example environment file:
cp .env.example .env
This creates a new .env file in your project root, which you will then populate with your specific credentials.
Open the newly created .env file and fill in the required variables. AI Docs includes server-side validation to ensure all critical variables are present and correctly formatted, preventing runtime errors.
Never commit your .env file to version control. It contains sensitive information that should remain confidential.
AI Docs categorizes environment variables by the services and functionalities they support.
These variables are crucial for connecting AI Docs to your PostgreSQL database.
DATABASE_URL (Required): Your PostgreSQL connection string. This is used by Drizzle ORM to connect to your database.
DATABASE_URL="postgresql://user:password@host:port/database"
For more information on setting up your database and managing schemas, refer to Database Architecture with Drizzle ORM.
These variables manage user authentication, primarily through Google and GitHub OAuth, and secure session management using better-auth.
GOOGLE_CLIENT_ID (Required): Your Google OAuth client ID.
GOOGLE_CLIENT_SECRET (Required): Your Google OAuth client secret.
GITHUB_CLIENT_ID (Optional): Your GitHub OAuth App client ID.
GITHUB_CLIENT_SECRET (Optional): Your GitHub OAuth App client secret.
BETTER_AUTH_SECRET (Required): A strong, random secret key used by better-auth for session management and security.
BETTER_AUTH_URL (Optional): The base URL for your authentication callbacks. For local development, this is typically http://localhost:3000. In production, it should be your application's domain (e.g., https://your-domain.com).
NEXT_PUBLIC_APP_URL (Optional): The public URL of your application, used for client-side redirects and other public-facing links. For local development, this is http://localhost:3000. This variable is prefixed with NEXT_PUBLIC_ to make it accessible in the browser.
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_CLIENT_ID=your-github-oauth-client-id
GITHUB_CLIENT_SECRET=your-github-oauth-client-secret
BETTER_AUTH_SECRET=your-random-32-char-secret
BETTER_AUTH_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000
BETTER_AUTH_SECRET is critical for security. Ensure it is a long, random string and kept confidential. You can generate one using openssl rand -base64 32.
[!info] For detailed steps on configuring Google OAuth, see Google OAuth Configuration. Further details on the authentication system are available in Authentication and User Management.
These keys enable AI Docs to interact with various AI models for codebase analysis and content generation.
OPENAI_API_KEY (Required): Your API key for OpenAI services.
GOOGLE_GENERATIVE_AI_API_KEY (Required): Your API key for Google Generative AI services, if you plan to use Google's models.
OPENAI_API_KEY=sk-your-openai-api-key
GOOGLE_GENERATIVE_AI_API_KEY=your-google-generative-ai-api-key
These keys are fundamental to the AI-Powered Generation process and are further explored in AI-Powered Generation.
These variables facilitate AI Docs' interaction with GitHub repositories for automated documentation generation and updates.
GITHUB_TOKEN (Required): A personal access token with repo scope for the AI Docs application to interact with GitHub. This is used for initial repository checks and webhook creation.
RESEND_API_KEY (Required): An API key for Resend, used for sending welcome emails and other transactional emails.
GITHUB_TOKEN=ghp_your-github-personal-access-token
RESEND_API_KEY=re_your-resend-api-key
Connecting your GitHub account via user settings allows AI Docs to access your private repositories. The GITHUB_TOKEN is used for general application-level GitHub interactions. For more details, see GitHub Integration.
These credentials are vital for enabling semantic search and Retrieval-Augmented Generation (RAG) features within AI Docs.
QDRANT_URL (Required): The URL of your Qdrant instance.
QDRANT_API_KEY (Required): The API key for authenticating with your Qdrant instance.
QDRANT_URL=https://your-qdrant-instance.com
QDRANT_API_KEY=your-qdrant-api-key
These credentials are vital for the semantic search capabilities and RAG features described in Vector Search with Qdrant and Deep Dive into Search & RAG.
Inngest is used for orchestrating background tasks such as repository ingestion and documentation generation.
INNGEST_EVENT_KEY (Required): Your Inngest event key for sending background jobs.
INNGEST_SIGNING_KEY (Optional): Your Inngest signing key, recommended for production environments to secure webhooks.
INNGEST_EVENT_KEY=your-inngest-event-key
INNGEST_SIGNING_KEY=your-inngest-signing-key
These optional variables are for advanced deployments that support multi-tenant architectures, such as custom domains and subdomain routing for projects.
MAIN_APP_DOMAINS (Optional): A comma-separated list of domains that serve the main application (e.g., localhost:3000,docup.dev).
ENABLE_SUBDOMAIN_ROUTING (Optional): Set to true or false to enable or disable subdomain-based routing for projects.
MAIN_APP_DOMAINS=localhost:3000,your-domain.com
ENABLE_SUBDOMAIN_ROUTING=true
For more details on configuring custom domains, refer to Project Settings and Customization.
These variables integrate AI Docs with the billing and subscription management system.
DODO_PAYMENTS_API_KEY (Required): Your API key for the Dodo Payments service.
DODO_WEBHOOK_SECRET (Required): The webhook secret for Dodo Payments, used to verify incoming webhook events.
DODO_PRO_MONTHLY_PRODUCT_ID (Required): The product ID for the monthly Pro plan in Dodo Payments.
DODO_PRO_ANNUAL_PRODUCT_ID (Required): The product ID for the annual Pro plan in Dodo Payments.
DODO_PAYMENTS_API_KEY=your-dodo-payments-api-key
DODO_WEBHOOK_SECRET=your-dodo-webhook-secret
DODO_PRO_MONTHLY_PRODUCT_ID=prod_monthly_id
DODO_PRO_ANNUAL_PRODUCT_ID=prod_annual_id
These variables are crucial for managing user plans and features, as detailed in Subscription Plans and Managing Your Subscription.
Variables prefixed with NEXT_PUBLIC_ are exposed to the client-side of the application.
NEXT_PUBLIC_APP_URL (Optional): As mentioned in Authentication Configuration, this is the public URL of your application.
NEXT_PUBLIC_SUPABASE_URL (Optional): URL for Supabase integration, if used for specific features.
NEXT_PUBLIC_SUPABASE_ANON_KEY (Optional): Anonymous key for Supabase integration.
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_SUPABASE_URL=https://your-supabase-url.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key
Variables without the NEXT_PUBLIC_ prefix are only available on the server-side, ensuring sensitive information is never exposed to the browser.
AI Docs incorporates robust server-side validation for environment variables. This validation, typically performed at application startup, ensures that all required configurations are present and correctly formatted. If critical variables are missing or malformed, the application will log errors and, in production environments, may prevent startup to avoid unexpected behavior.
// Simplified example of environment variable validation
import { z } from "zod";
const serverEnvSchema = z.object({
DATABASE_URL: z.string().min(1, "DATABASE_URL is required"),
GOOGLE_CLIENT_ID: z.string().min(1, "GOOGLE_CLIENT_ID is required"),
BETTER_AUTH_SECRET: z.string().min(32, "BETTER_AUTH_SECRET must be at least 32 characters"),
OPENAI_API_KEY: z.string().min(1, "OPENAI_API_KEY is required"),
// ... other server-side variables
});
// Validation logic runs on server startup
function validateServerEnvironment() {
const parsed = serverEnvSchema.safeParse(process.env);
if (!parsed.success) {
console.error("❌ Missing or invalid server environment variables:", parsed.error.flatten().fieldErrors);
if (process.env.NODE_ENV === "production") {
throw new Error("Invalid environment variables. Please check your .env file or deployment configuration.");
}
}
}
validateServerEnvironment();
When managing environment variables, always adhere to these security best practices:
BETTER_AUTH_SECRET. Tools like openssl rand -base64 32 can help generate these.GITHUB_TOKEN) have only the minimum necessary permissions.When deploying AI Docs to a production environment, you will configure environment variables through your hosting provider's interface (e.g., Vercel, Netlify, AWS). These platforms provide secure mechanisms to store and inject environment variables at build or runtime, ensuring they are not exposed in your codebase.
For detailed instructions and best practices on deploying AI Docs, refer to Deployment to Production.
With a clear understanding of environment variables and how to configure them, you are well-prepared to set up and run AI Docs.