Configuration Requirements for Deploying CodeWiki: Complete Setup Guide

Deploying CodeWiki requires Python 3.9+, three mandatory API keys (GitHub, Gemini, and Google), and environment variables configured in a .env file before starting the FastAPI server with Uvicorn.

CodeWiki is a FastAPI-based backend service that generates AI-driven system diagrams and wikis from GitHub repositories. To deploy it successfully, you must configure runtime dependencies, environment variables, and static configuration constants. This guide covers the complete configuration requirements for deploying CodeWiki based on the source code in quangdungluong/codewiki.

Runtime Environment Requirements

CodeWiki requires Python 3.9 or higher and several Python packages defined throughout the import statements in the codebase.

Required Dependencies

The following packages must be installed (as referenced in api/main.py, api/stream_chat.py, and utils/repository_structure.py):

• FastAPI – Web framework
• Uvicorn – ASGI server
• httpx – Async HTTP client
• requests – Synchronous HTTP client
• python-dotenv – Environment variable loading
• pydantic – Data validation

Installation Commands

# Clone the repository

git clone https://github.com/quangdungluong/codewiki.git
cd codewiki

# Create virtual environment

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies

pip install fastapi uvicorn httpx requests python-dotenv pydantic

Environment Variables Configuration

CodeWiki requires specific environment variables defined in a .env file at the project root. The python-dotenv loader is called in api/main.py (lines 9-11) to load these variables.

Mandatory API Keys

Variable	Purpose	Source File Reference
GITHUB_API_KEY	Token for accessing private GitHub repositories	Used in utils/repository_structure.py
GEMINI_API_KEY	Google Gemini model key for AI content generation	Read in api/services/gemini_service.py (line 13)
GOOGLE_API_KEY	Google AI key for the chat streaming endpoint	Read in api/stream_chat.py (line 14)

Server Configuration

• PORT – Port on which the FastAPI server listens (default: 8001). Defined in api/main.py (line 17).

Sample .env File

# .env - Local development configuration

GITHUB_API_KEY=ghp_YourPersonalAccessTokenHere
GEMINI_API_KEY=AIzaSyYourGeminiApiKeyHere
GOOGLE_API_KEY=AIzaSyYourGoogleApiKeyHere
PORT=8001

Note: The .env file is automatically excluded from repository processing (see config.py lines 63-66) to prevent accidental exposure of secrets.

Static Configuration

Beyond environment variables, CodeWiki uses static configuration files for internal behavior.

Target Server URL

The TARGET_SERVER_BASE_URL constant in utils/constants.py (line 4) defines the base URL that internal components use to call the API. Default value:

# utils/constants.py

TARGET_SERVER_BASE_URL = "http://localhost:8001"

Change this if running behind a reverse proxy or on a different host:

TARGET_SERVER_BASE_URL = "https://wiki.mycompany.com"

File Exclusion Lists

The config.py file defines default exclusions for repository scanning to avoid processing unnecessary files:

• DEFAULT_EXCLUDED_DIRS – Directories to ignore (e.g., .git, node_modules, __pycache__)
• DEFAULT_EXCLUDED_FILES – File patterns to skip (e.g., package-lock.json, .env)

These are defined in config.py (lines 4-66) and used by the RepositoryStructureFetcher class in utils/repository_structure.py.

Starting the Server

Once configuration is complete, start the FastAPI application using Uvicorn.

Basic Startup Command

uvicorn api.main:app --host 0.0.0.0 --port 8001 --workers 2

The entry point api/main.py invokes uvicorn.run("api.api:app", ...) after loading environment variables (lines 11-19).

Docker Deployment Example

docker run -d \
  -p 8001:8001 \
  -v "$(pwd)/.cache:/app/.cache" \
  -v "$(pwd)/.env:/app/.env:ro" \
  --name codewiki \
  python:3.11-slim bash -c "\
    pip install fastapi uvicorn httpx requests python-dotenv pydantic && \
    uvicorn api.main:app --host 0.0.0.0 --port \${PORT:-8001} --workers 2"

Volume mounts explained:

• ./.cache – Persists wiki and diagram caches across container restarts
• ./.env – Read-only mount for environment configuration

Production Considerations

For production deployments of CodeWiki, implement the following optimizations:

Process Management

Use Gunicorn with Uvicorn workers instead of running Uvicorn directly:

gunicorn api.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8001

TLS Termination

Place CodeWiki behind an HTTPS-terminating reverse proxy (NGINX, Traefik, or Caddy). Update TARGET_SERVER_BASE_URL in utils/constants.py to reflect the public HTTPS address.

Scaling Characteristics

The codebase uses httpx.AsyncClient for asynchronous GitHub API calls and implements limited concurrency for page generation. Additional worker processes can be added to handle more simultaneous requests, but monitor the Google Gemini API rate limits.

Cache Persistence

Wiki and diagram caches are stored in:

• ./.cache/wiki_cache
• ./.cache/diagram_cache

As defined in utils/constants.py (lines 6-9). Mount these to persistent volumes in containerized environments to avoid regenerating content after restarts.

Logging

All modules emit structured logs via utils/logger.py. Forward stdout and stderr to your centralized logging system (ELK, Loki, or CloudWatch).

Summary

Deploying CodeWiki requires careful attention to three configuration layers:

• Runtime Environment: Python 3.9+ with FastAPI, Uvicorn, and HTTP client libraries installed
• Environment Variables: Mandatory API keys for GitHub (GITHUB_API_KEY), Gemini (GEMINI_API_KEY), and Google (GOOGLE_API_KEY), plus optional PORT configuration
• Static Configuration: TARGET_SERVER_BASE_URL in utils/constants.py for internal routing, and exclusion lists in config.py for repository scanning

Once configured, start the service with uvicorn api.main:app and verify health via the /api/language_config endpoint.

Frequently Asked Questions

What happens if I don't set the GEMINI_API_KEY environment variable?

The application will fail to initialize the Gemini service wrapper in api/services/gemini_service.py (line 13), causing AI-driven wiki generation and diagram creation to fail. You must provide a valid Google Gemini API key for the core functionality to work.

Can I deploy CodeWiki without a GitHub API key?

You can deploy the service without GITHUB_API_KEY, but you will only be able to process public repositories. The GITHUB_API_KEY is required in utils/repository_structure.py to authenticate against the GitHub API and access private repositories or avoid rate limiting on public ones.

How do I change the default port from 8001?

Set the PORT environment variable in your .env file or export it before starting the server. The value is read in api/main.py (line 17) and passed to the Uvicorn server. Alternatively, override it directly in the Uvicorn command line with --port 8080.

Where are the generated wikis and diagrams cached?

Generated content is stored in ./.cache/wiki_cache and ./.cache/diagram_cache as defined in utils/constants.py (lines 6-9). In production deployments, mount these directories to persistent volumes to ensure cache survival across container restarts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}