# Environment Variables Needed to Deploy CodeWiki: Complete Configuration Guide

> Learn the essential environment variables like PORT, GITHUB_API_KEY, and GEMINI_API_KEY needed to successfully deploy your CodeWiki application. Get the complete configuration guide now.

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

---

**Deploying CodeWiki requires configuring four essential environment variables: `PORT` for server binding, `GITHUB_API_KEY` for repository access, and `GEMINI_API_KEY` or `GOOGLE_API_KEY` for AI service authentication.**

CodeWiki, the open-source documentation generator maintained at `quangdungluong/codewiki`, relies on environment variables to configure its FastAPI server and authenticate with external APIs. Understanding the environment variables needed to deploy CodeWiki is critical for both local development and production deployments, as these settings control server ports, GitHub repository access, and Google AI integrations.

## Required Environment Variables for CodeWiki Deployment

The application reads configuration at runtime using `os.getenv` and `os.environ.get` calls distributed across the codebase. You must configure the following variables before starting the server to ensure full functionality.

### PORT: Server Configuration

The `PORT` variable defines the HTTP port where the FastAPI server listens for incoming requests.

- **Default value**: `8001` (used if `PORT` is unset)
- **Source file**: [[`api/main.py`](https://github.com/quangdungluong/codewiki/blob/main/api/main.py)](https://github.com/quangdungluong/codewiki/blob/master/api/main.py) at line 17
- **Usage**: The application passes this value directly to the Uvicorn server configuration

### GITHUB_API_KEY: Repository Authentication

The `GITHUB_API_KEY` provides a GitHub personal access token that authorizes the `GithubService` class to fetch repository trees and README files.

- **Required for**: Accessing private repositories; public repos may work without it depending on API rate limits
- **Source file**: [[`api/services/github_service.py`](https://github.com/quangdungluong/codewiki/blob/main/api/services/github_service.py)](https://github.com/quangdungluong/codewiki/blob/master/api/services/github_service.py) receives the token from callers, and [[`tests/test_repository_structure.py`](https://github.com/quangdungluong/codewiki/blob/main/tests/test_repository_structure.py)](https://github.com/quangdungluong/codewiki/blob/master/tests/test_repository_structure.py) at line 22 demonstrates loading it from the environment
- **Security note**: Never commit this token to source control; the repository includes `.env` in its ignore patterns via [[`config.py`](https://github.com/quangdungluong/codewiki/blob/main/config.py)](https://github.com/quangdungluong/codewiki/blob/master/config.py)

### GEMINI_API_KEY: Google Gemini Integration

The `GEMINI_API_KEY` authenticates requests to Google Gemini models through the `GeminiService` class.

- **Source file**: [[`api/services/gemini_service.py`](https://github.com/quangdungluong/codewiki/blob/main/api/services/gemini_service.py)](https://github.com/quangdungluong/codewiki/blob/master/api/services/gemini_service.py) at line 13
- **Usage**: The service initializes a `genai` client using this key to generate documentation and code explanations

### GOOGLE_API_KEY: Generative AI Chat Services

The `GOOGLE_API_KEY` provides authentication for the Google Generative AI client used in the streaming chat endpoint.

- **Source file**: [[`api/stream_chat.py`](https://github.com/quangdungluong/codewiki/blob/main/api/stream_chat.py)](https://github.com/quangdungluong/codewiki/blob/master/api/stream_chat.py) at line 14
- **Distinction**: While `GEMINI_API_KEY` targets the Gemini-specific service class, `GOOGLE_API_KEY` is used directly in the chat streaming implementation

## Configuring Environment Variables for Deployment

You can supply these variables through a `.env` file, your hosting platform's secret management system, or direct environment injection. The project uses `python-dotenv` to automatically load variables from a `.env` file in the project root.

### Minimal .env Configuration

Create a `.env` file in the project root with the following structure:

```dotenv

# Server configuration

PORT=8001

# GitHub access (required for private repositories)

GITHUB_API_KEY=ghp_YourGitHubTokenHere

# Google AI services (required for documentation generation features)

GEMINI_API_KEY=your-gemini-api-key
GOOGLE_API_KEY=your-google-api-key

```

The application automatically loads these values via `python-dotenv`, which is invoked in [[`api/main.py`](https://github.com/quangdungluong/codewiki/blob/main/api/main.py)](https://github.com/quangdungluong/codewiki/blob/master/api/main.py).

### Starting the Server

With your `.env` file configured, start the FastAPI application:

```bash

# Install dependencies

pip install -r requirements.txt

# Run the server (automatically picks up PORT from environment)

python -m api.main

```

Uvicorn will bind to the port specified in your `PORT` variable, or default to `8001` if unset.

## Programmatic Access to Environment Variables

When extending CodeWiki or writing tests, access these variables using standard Python `os` module patterns as implemented in the codebase.

### Accessing GitHub API Key in Custom Scripts

```python
import os
from api.services.github_service import GithubService

# Load from environment (matches pattern in tests/test_repository_structure.py line 22)

token = os.getenv("GITHUB_API_KEY")

# Initialize service for private repository access

service = GithubService(
    owner="quangdungluong", 
    repo="codewiki", 
    token=token
)

file_tree, default_branch = service.get_tree_data()
print(f"Default branch: {default_branch}")

```

### Initializing Gemini Service

```python
from api.services.gemini_service import GeminiService

# Constructor automatically reads GEMINI_API_KEY from environment (api/services/gemini_service.py line 13)

gemini = GeminiService()

# Service is now ready for documentation generation

```

## Summary

Deploying CodeWiki successfully requires configuring four specific environment variables that control server behavior and external API authentication:

- **`PORT`** – Configures the FastAPI server listening port (default 8001), defined in [`api/main.py`](https://github.com/quangdungluong/codewiki/blob/main/api/main.py)
- **`GITHUB_API_KEY`** – Authenticates GitHub API requests for repository access, used in [`api/services/github_service.py`](https://github.com/quangdungluong/codewiki/blob/main/api/services/github_service.py)
- **`GEMINI_API_KEY`** – Powers Google Gemini model integration via [`api/services/gemini_service.py`](https://github.com/quangdungluong/codewiki/blob/main/api/services/gemini_service.py)
- **`GOOGLE_API_KEY`** – Enables streaming chat functionality in [`api/stream_chat.py`](https://github.com/quangdungluong/codewiki/blob/main/api/stream_chat.py)

Supply these through a `.env` file or your deployment platform's secret management system, ensuring `GITHUB_API_KEY` remains protected and never committed to version control.

## Frequently Asked Questions

### What happens if I don't set the GITHUB_API_KEY?

Without `GITHUB_API_KEY`, CodeWiki cannot access private GitHub repositories and will encounter authentication errors when attempting to fetch repository trees or README files. While public repositories might work temporarily depending on GitHub's unauthenticated rate limits (60 requests per hour), production deployments absolutely require this token for reliable operation.

### Can I deploy CodeWiki without the Google AI API keys?

You can start the server without `GEMINI_API_KEY` and `GOOGLE_API_KEY`, but functionality will be severely limited. The `GeminiService` class in [`api/services/gemini_service.py`](https://github.com/quangdungluong/codewiki/blob/main/api/services/gemini_service.py) requires `GEMINI_API_KEY` to initialize the generative AI client, and [`api/stream_chat.py`](https://github.com/quangdungluong/codewiki/blob/main/api/stream_chat.py) requires `GOOGLE_API_KEY` for the streaming chat endpoint. Without these, documentation generation and chat features will fail.

### How do I configure these variables in a Docker deployment?

When deploying CodeWiki in a Docker container, pass environment variables using the `-e` flag or an env file:

```bash
docker run -e PORT=8001 \
           -e GITHUB_API_KEY=ghp_your_token \
           -e GEMINI_API_KEY=your_gemini_key \
           -e GOOGLE_API_KEY=your_google_key \
           codewiki:latest

```

Alternatively, use Docker Compose with an `.env` file in your project root, ensuring the file is referenced in your [`docker-compose.yml`](https://github.com/quangdungluong/codewiki/blob/main/docker-compose.yml) under the `env_file` directive or `environment` section.

### Is the PORT environment variable mandatory?

No, `PORT` is optional. If not specified, CodeWiki defaults to port `8001` as implemented in [`api/main.py`](https://github.com/quangdungluong/codewiki/blob/main/api/main.py) at line 17. However, explicitly setting this variable is recommended for production deployments where you may need to bind to a specific port dictated by your hosting platform (such as Heroku's dynamic port assignment or cloud container requirements).