# Configuration Requirements for Deploying CodeWiki: Complete Setup Guide

> Deploying CodeWiki needs Python 3.9, GitHub, Gemini, and Google API keys. Set up environment variables in .env to configure your FastAPI server.

- Repository: [Luong Quang Dung/codewiki](https://github.com/quangdungluong/codewiki)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/quangdungluong/codewiki/blob/main/api/main.py), [`api/stream_chat.py`](https://github.com/quangdungluong/codewiki/blob/main/api/stream_chat.py), and [`utils/repository_structure.py`](https://github.com/quangdungluong/codewiki/blob/main/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

```bash

# 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`](https://github.com/quangdungluong/codewiki/blob/main/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`](https://github.com/quangdungluong/codewiki/blob/main/utils/repository_structure.py) |
| `GEMINI_API_KEY` | Google Gemini model key for AI content generation | Read in [`api/services/gemini_service.py`](https://github.com/quangdungluong/codewiki/blob/main/api/services/gemini_service.py) (line 13) |
| `GOOGLE_API_KEY` | Google AI key for the chat streaming endpoint | Read in [`api/stream_chat.py`](https://github.com/quangdungluong/codewiki/blob/main/api/stream_chat.py) (line 14) |

### Server Configuration

- **`PORT`** – Port on which the FastAPI server listens (default: `8001`). Defined in [`api/main.py`](https://github.com/quangdungluong/codewiki/blob/main/api/main.py) (line 17).

### Sample .env File

```dotenv

# .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`](https://github.com/quangdungluong/codewiki/blob/main/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`](https://github.com/quangdungluong/codewiki/blob/main/utils/constants.py) (line 4) defines the base URL that internal components use to call the API. Default value:

```python

# utils/constants.py

TARGET_SERVER_BASE_URL = "http://localhost:8001"

```

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

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

```

### File Exclusion Lists

The [`config.py`](https://github.com/quangdungluong/codewiki/blob/main/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`](https://github.com/quangdungluong/codewiki/blob/main/package-lock.json), `.env`)

These are defined in [`config.py`](https://github.com/quangdungluong/codewiki/blob/main/config.py) (lines 4-66) and used by the `RepositoryStructureFetcher` class in [`utils/repository_structure.py`](https://github.com/quangdungluong/codewiki/blob/main/utils/repository_structure.py).

## Starting the Server

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

### Basic Startup Command

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

```

The entry point [`api/main.py`](https://github.com/quangdungluong/codewiki/blob/main/api/main.py) invokes `uvicorn.run("api.api:app", ...)` after loading environment variables (lines 11-19).

### Docker Deployment Example

```bash
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:

```bash
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`](https://github.com/quangdungluong/codewiki/blob/main/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`](https://github.com/quangdungluong/codewiki/blob/main/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`](https://github.com/quangdungluong/codewiki/blob/main/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`](https://github.com/quangdungluong/codewiki/blob/main/utils/constants.py) for internal routing, and exclusion lists in [`config.py`](https://github.com/quangdungluong/codewiki/blob/main/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`](https://github.com/quangdungluong/codewiki/blob/main/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`](https://github.com/quangdungluong/codewiki/blob/main/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`](https://github.com/quangdungluong/codewiki/blob/main/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`](https://github.com/quangdungluong/codewiki/blob/main/utils/constants.py) (lines 6-9). In production deployments, mount these directories to persistent volumes to ensure cache survival across container restarts.