Installation Guide

Detailed installation instructions for DeepWiki-Open including dependencies, system requirements, and setup options

This guide covers detailed installation instructions for DeepWiki-Open, including system requirements, dependencies, and various setup options.

System Requirements

Minimum Requirements

• OS: Linux, macOS, or Windows 10+
• Python: 3.8 or higher
• Node.js: 16.0 or higher
• Memory: 4GB RAM minimum
• Storage: 2GB free space
• Network: Internet connection for AI API calls

Recommended Requirements

• OS: Linux (Ubuntu 20.04+) or macOS
• Python: 3.9 or 3.10
• Node.js: 18.0 or higher
• Memory: 8GB RAM or more
• Storage: 10GB free space (for repository caches)
• Network: Stable broadband connection

Prerequisites

Before installing DeepWiki-Open, ensure you have:

1. Python Installation

   macOS

   # Using Homebrew
   brew install python@3.10
   
   # Or download from python.org
   # https://www.python.org/downloads/
   

   Linux (Ubuntu/Debian)

   sudo apt update
   sudo apt install python3.10 python3.10-venv python3-pip
   

   Windows

   # Using Chocolatey
   choco install python3
   
   # Or download from python.org
   # https://www.python.org/downloads/
   

   Verify Python installation: python --version should show 3.8+

2. Node.js Installation

   macOS

   # Using Homebrew
   brew install node
   
   # Or using Node Version Manager
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
   nvm install 18
   nvm use 18
   

   Linux

   # Using NodeSource repository
   curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
   sudo apt-get install -y nodejs
   
   # Or using NVM
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
   nvm install 18
   nvm use 18
   

   Windows

   # Using Chocolatey
   choco install nodejs
   
   # Or download from nodejs.org
   # https://nodejs.org/
   

   Verify Node.js installation: node --version should show 16.0+

3. Git Installation

   macOS

   # Git comes with Xcode Command Line Tools
   xcode-select --install
   
   # Or using Homebrew
   brew install git
   

   Linux

   sudo apt update
   sudo apt install git
   

   Windows

   # Using Chocolatey
   choco install git
   
   # Or download from git-scm.com
   # https://git-scm.com/download/win
   

   Verify Git installation: git --version

Installation Methods

Choose the installation method that best fits your needs:

Docker (Recommended)

Docker Installation

Docker provides the easiest and most consistent setup experience.

Prerequisites for Docker

1. Install Docker

   macOS

   Download and install Docker Desktop for Mac

   Linux

   # Ubuntu/Debian
   curl -fsSL https://get.docker.com -o get-docker.sh
   sudo sh get-docker.sh
   
   # Add user to docker group
   sudo usermod -aG docker $USER
   # Log out and back in for group change to take effect
   

   Windows

   Download and install Docker Desktop for Windows

2. Install Docker Compose

   Docker Compose is typically included with Docker Desktop. For Linux:

   sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
   sudo chmod +x /usr/local/bin/docker-compose
   

Docker Setup

1. Clone Repository

   git clone https://github.com/AsyncFuncAI/deepwiki-open.git
   cd deepwiki-open
   
2. Configure Environment

   # Create .env file
   cp .env.example .env
   
   # Edit with your API keys
   nano .env  # or use your preferred editor
   
3. Start Services

   docker-compose up -d
   

   This starts both backend (port 8001) and frontend (port 3000) services.

Manual Installation

Manual Installation

For development or when you need more control over the setup.

1. Clone Repository

   git clone https://github.com/AsyncFuncAI/deepwiki-open.git
   cd deepwiki-open
   
2. Backend Setup

   # Create Python virtual environment
   python -m venv venv
   
   # Activate virtual environment
   # On macOS/Linux:
   source venv/bin/activate
   # On Windows:
   # venv\Scripts\activate
   
   # Install Python dependencies
   pip install -r api/requirements.txt
   

   Using a virtual environment is strongly recommended to avoid dependency conflicts.

3. Frontend Setup

   # Install Node.js dependencies
   npm install
   # or if you prefer yarn:
   # yarn install
   
4. Environment Configuration

   Create a .env file in the project root:

   # Copy example environment file
   cp .env.example .env
   
   # Edit environment variables
   nano .env
   

   Required variables:

   GOOGLE_API_KEY=your_google_api_key
   OPENAI_API_KEY=your_openai_api_key
   
5. Start Services

   Open two terminal windows:

   Terminal 1 (Backend):

   # Ensure virtual environment is activated
   source venv/bin/activate  # or venv\Scripts\activate on Windows
   python -m api.main
   

   Terminal 2 (Frontend):

   npm run dev
   # or: yarn dev
   

Development Setup

Development Setup

For contributors and developers who want to modify DeepWiki-Open.

1. Fork Repository

   1. Fork the repository on GitHub
   2. Clone your fork:

   git clone https://github.com/YOUR_USERNAME/deepwiki-open.git
   cd deepwiki-open
   
2. Set Up Development Environment

   # Install Python development dependencies
   pip install -r api/requirements.txt
   pip install -r api/requirements-dev.txt  # if exists
   
   # Install Node.js development dependencies
   npm install
   
   # Install pre-commit hooks (if available)
   pre-commit install
   
3. Configure Development Settings

   Create .env.development:

   # Development environment
   NODE_ENV=development
   LOG_LEVEL=DEBUG
   LOG_FILE_PATH=./api/logs/development.log
   
   # API Configuration
   PORT=8001
   SERVER_BASE_URL=http://localhost:8001
   
   # Your API keys
   GOOGLE_API_KEY=your_google_api_key
   OPENAI_API_KEY=your_openai_api_key
   
4. Set Up Hot Reloading

   For development with hot reloading:

   # Terminal 1: Backend with auto-reload
   python -m api.main  # Already includes reload in development
   
   # Terminal 2: Frontend with Turbopack
   npm run dev  # Uses Next.js Turbopack for fast refresh
   

Verification

After installation, verify that everything is working correctly:

1. Check Backend Health

   # Test backend API
   curl http://localhost:8001/health
   
   # Or visit in browser
   open http://localhost:8001/docs
   

   Expected response:

   {"status": "healthy", "version": "0.1.0"}
   
2. Check Frontend

   Visit http://localhost:3000 in your browser.

   You should see:

   • DeepWiki-Open interface
   • Repository URL input field
   • Model selection dropdown
   • Generate Wiki button
3. Test Full Workflow

   1. Enter a small public repository (e.g., https://github.com/octocat/Hello-World)
   2. Select an AI model provider
   3. Click “Generate Wiki”
   4. Verify wiki generation completes successfully

Optional Dependencies

Ollama (Local AI Models)

To run AI models locally using Ollama:

macOS

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Or using Homebrew
brew install ollama

# Start Ollama service
ollama serve

# Pull a model
ollama pull llama3:8b

Linux

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Start as service
sudo systemctl start ollama
sudo systemctl enable ollama

# Pull a model
ollama pull llama3:8b

Windows

Download and install from Ollama website

Then in PowerShell:

ollama pull llama3:8b

Update your .env:

OLLAMA_HOST=http://localhost:11434

Redis (Caching)

For improved performance in production:

macOS

brew install redis
brew services start redis

Linux

sudo apt update
sudo apt install redis-server
sudo systemctl start redis
sudo systemctl enable redis

Docker

docker run -d -p 6379:6379 redis:alpine

Add to .env:

REDIS_URL=redis://localhost:6379

Troubleshooting Installation

Python Installation Issues

Problem: python: command not found

Solutions:

# Check if python3 is available
python3 --version

# Create alias (add to ~/.bashrc or ~/.zshrc)
alias python=python3

# Or install Python properly
sudo apt install python-is-python3  # Ubuntu/Debian

Node.js Installation Issues

Problem: npm ERR! EACCES: permission denied

Solutions:

# Use Node Version Manager (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

# Or fix npm permissions
sudo chown -R $(whoami) ~/.npm

Docker Issues

Problem: Cannot connect to Docker daemon

Solutions:

# Start Docker service
sudo systemctl start docker

# Add user to docker group
sudo usermod -aG docker $USER
# Then log out and back in

# Or run with sudo (not recommended for development)
sudo docker-compose up

Port Conflicts

Problem: Port already in use

Solutions:

# Find what's using the port
lsof -i :3000  # or :8001

# Kill the process
kill -9 PID

# Or use different ports in .env
PORT=8002
# Update frontend to use new backend port

Next Steps

Environment Configuration

Configure API keys and environment settings

Model Providers Setup

Set up AI model providers for documentation generation

Generate Your First Wiki

Create your first repository wiki

Production Deployment

Deploy DeepWiki for production use