Running AI Docs Locally

This guide provides a step-by-step walkthrough to set up and run AI Docs on your local machine. By following these instructions, you'll prepare your development environment, configure essential services, and launch the application, enabling you to begin generating documentation from your GitHub repositories.

Prerequisites

Before proceeding with the installation, ensure your development environment meets the following requirements. For a comprehensive overview of all necessary software and services, refer to Installation and Prerequisites.

• Node.js: Version 18 or higher. AI Docs is built with Next.js, which requires a modern Node.js runtime.
• pnpm: The preferred package manager for AI Docs, known for its efficiency. If you don't have it, install it globally:
  bash

  npm install -g pnpm
  

• PostgreSQL Database: A running instance of a PostgreSQL database. You will need its connection string. For more details on database setup, refer to Database Architecture with Drizzle ORM.
• Google OAuth Credentials: A Client ID and Client Secret from the Google Cloud Console for user authentication. These are essential for enabling user login. For a detailed setup guide, see Google OAuth Configuration.
• OpenAI API Key: An API key from OpenAI, required for the AI-powered documentation generation features. This key enables AI Docs to analyze your codebase and generate content. Refer to AI-Powered Generation for more information.
• Qdrant Instance (Optional): While AI Docs can run without a dedicated Qdrant instance for basic functionality, it is required for advanced features like semantic search and Retrieval-Augmented Generation (RAG). You'll need its URL and API key. Refer to Vector Search with Qdrant for more details.

Installation Steps

Follow these steps to get AI Docs running on your local machine.

Step 1: Clone the Repository

Start by cloning the AI Docs repository from GitHub to your local machine and navigate into the project directory.

git clone <your-repo-url>
cd ai-docs

Step 2: Install Dependencies

Once inside the project directory, install all necessary dependencies using pnpm.

pnpm install

Step 3: Configure Environment Variables

AI Docs relies on several environment variables for database connection, authentication, and AI services.

1. Create your .env file: Copy the provided example environment file to create your local configuration file:

   bash

   cp .env.example .env
   

2. Update .env variables: Open the newly created .env file and populate the following variables with your specific credentials and settings:

   env

   # Database connection string for your PostgreSQL database
   DATABASE_URL="your-postgresql-connection-string"
   
   # Google OAuth credentials for user authentication
   GOOGLE_CLIENT_ID=your-google-client-id
   GOOGLE_CLIENT_SECRET=your-google-client-secret
   
   # Better Auth secret key for session management
   BETTER_AUTH_SECRET=your-random-secret-key
   # Generate a strong secret with: openssl rand -base64 32
   
   # Local development URLs for Better Auth and the Next.js app
   BETTER_AUTH_URL=http://localhost:3000
   NEXT_PUBLIC_APP_URL=http://localhost:3000
   
   # OpenAI API Key for AI generation features
   OPENAI_API_KEY=your-openai-api-key
   

   For detailed instructions on obtaining GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET, refer to the Google OAuth Configuration page. The OPENAI_API_KEY setup is covered in Environment Configuration.

   Many other environment variables exist for advanced features like GitHub integration, Qdrant, and Inngest. For a comprehensive guide to all available variables, consult the Environment Configuration page.

Step 4: Set Up the Database

AI Docs uses Drizzle ORM for database management. After configuring your DATABASE_URL, you need to generate and push the database schema.

pnpm db:generate
pnpm db:push

• pnpm db:generate: This command generates Drizzle migrations based on your schema definitions.
• pnpm db:push: This command applies the generated schema changes to your PostgreSQL database.

Step 5: Run the Development Server

With all prerequisites and configurations in place, you can now start the AI Docs development server.

pnpm dev

This command will start the Next.js development server. Once it's running, open your web browser and navigate to http://localhost:3000 to see the application.

Setup Flow

The initial setup process follows a clear sequence to ensure all components are correctly initialized:

Next Steps

Congratulations! You have successfully installed and launched AI Docs locally. Here are some recommended next steps to get started with generating documentation:

• User Authentication: Before creating projects, you'll need to sign in. Learn more about setting up and managing user authentication with Google OAuth on the Authentication and User Management page.
• Creating Your First Project: Once authenticated, you can create your first documentation project by connecting a GitHub repository. The Creating a New Project page provides a comprehensive guide on how to do this.
• Environment Configuration: Dive deeper into advanced configuration options and understanding all necessary external service integrations.
• Troubleshooting and Support: If you encounter any issues during setup or operation, refer to the Troubleshooting and Support page for solutions and resources.