Generic Virtual Machine

System Requirements

Recommended Hardware

Required Software

Required Ports

Internet access is only required if you plan to connect with cloud-based Git services like GitHub, GitLab, or Bitbucket. For self-hosted Git tools within your network, external internet access is optional.

Domain Name Setup (Optional)

If you're planning to integrate Kodus with cloud-based Git providers (GitHub, GitLab, or Bitbucket), you'll need public-facing URLs for both the Kodus Web App and its API. This allows your server to receive webhooks for proper Code Review functionality and ensures correct application behavior. We recommend setting up two subdomains:

One for the Web Application, e.g., kodus-web.yourdomain.com.
One for the API, e.g., kodus-api.yourdomain.com.

Both subdomains should have DNS A records pointing to your server's IP address. Later in this guide, we will configure a reverse proxy (Nginx) to route requests to these subdomains to the correct internal services. This setup is essential for full functionality, including webhooks and authentication.

Note: If you're only connecting to self-hosted Git tools on your network and do not require public access or webhooks, you might be able to use a simpler setup, but this guide focuses on public-facing deployments.

Get the Kodus Installer

Clone our installer repository:

git clone https://github.com/kodustech/kodus-installer.git
cd kodus-installer

Configure Environment Variables

First, copy the example environment file:

cp .env.example .env

Generate secure keys for the required environment variables using:

# For most security keys
openssl rand -base64 32

# Specifically for API_CRYPTO_KEY and CODE_MANAGEMENT_SECRET
openssl rand -hex 32

# Specifically for CODE_MANAGEMENT_WEBHOOK_TOKEN
openssl rand -base64 32 | tr -d '=' | tr '/+' '_-'

You'll need to generate values for these security keys:

WEB_NEXTAUTH_SECRET (use openssl rand -base64 32)
WEB_JWT_SECRET_KEY (use openssl rand -base64 32)
API_CRYPTO_KEY (use openssl rand -hex 32)
API_JWT_SECRET (use openssl rand -base64 32)
API_JWT_REFRESHSECRET (use openssl rand -base64 32)
CODE_MANAGEMENT_SECRET (use openssl rand -hex 32)
CODE_MANAGEMENT_WEBHOOK_TOKEN (use openssl rand -base64 32 | tr -d '=' | tr '/+' '_-')

Never commit your .env file to version control. Keep your API keys and database credentials secure.

Then update your .env file with the following required variables:

# Core System Settings
WEB_NODE_ENV="self-hosted"                     # Keep as "self-hosted" for self-hosted setup
WEB_HOSTNAME_API="kodus-api.yourdomain.com"    # Public API hostname (e.g., kodus-api.yourdomain.com)
WEB_PORT_API=443                               # Public API port (usually 443 for HTTPS, or 80 if not using SSL yet)
WEB_PORT=3000                                  # Internal Web application port (reverse proxy will handle public port)
GLOBAL_API_CONTAINER_NAME="kodus-orchestrator" # API container name

# Authentication Settings
NEXTAUTH_URL="https://kodus-web.yourdomain.com" # Full public base URL for the Web App (e.g., https://kodus-web.yourdomain.com)
WEB_NEXTAUTH_SECRET=""                        # NextAuth secret key (generate with: openssl rand -base64 32)
WEB_JWT_SECRET_KEY=""                         # JWT secret key (generate with: openssl rand -base64 32)

# API Configuration
API_NODE_ENV="development"                    # Keep as "development" for local setup
API_LOG_LEVEL=error                           # Error logging level
API_LOG_PRETTY=true                           # Pretty print logs
API_HOST=0.0.0.0                              # API host
API_PORT=3001                                 # API port
API_RATE_MAX_REQUEST=100                      # Rate limiting: max requests
API_RATE_INTERVAL=1000                        # Rate limiting: time window (ms)
API_CRYPTO_KEY=                               # Crypto key (generate with: openssl rand -hex 32)
API_JWT_EXPIRES_IN=365d                       # JWT token expiration time
API_JWT_SECRET=                               # JWT secret key
API_JWT_REFRESHSECRET=                        # JWT refresh token secret key
API_JWT_REFRESH_EXPIRES_IN=7d                 # JWT refresh token expiration time

# Database Configuration
API_DATABASE_ENV="development"                # Database environment
API_PG_DB_HOST=db_kodus_postgres              # PostgreSQL host
API_PG_DB_PORT=5432                          # PostgreSQL port
API_PG_DB_USERNAME=kodusdev                  # Database username
API_PG_DB_PASSWORD=                          # Database password
API_PG_DB_DATABASE=kodus_db                  # Database name

# MongoDB Configuration
API_MG_DB_HOST=db_kodus_mongodb              # MongoDB host
API_MG_DB_PORT=27017                         # MongoDB port
API_MG_DB_USERNAME=kodusdev                  # Database username
API_MG_DB_PASSWORD=                          # Database password
API_MG_DB_DATABASE=kodus_db                  # Database name

Deployment Process

Need help?

Schedule a call with our founder to get help with your deployment.

LLM Integration Settings

Kodus offers two configuration modes for Language Models (LLMs):

This is the simplest mode and recommended for self-hosted installations. You only need to configure a single LLM model.

# Fixed Mode Configuration
API_LLM_PROVIDER_MODEL="gpt-3.5-turbo"     # Model you want to use
API_OPENAI_FORCE_BASE_URL="https://your-api.com/v1"  # Your API provider URL
API_OPEN_AI_API_KEY="your-api-key"          # Your API provider key

This mode is ideal for self-hosted because:

Requires only a single API key
Works with any OpenAI-compatible API provider
Easier to configure and maintain

Model Configuration Guides

Check our model-specific guides for detailed setup instructions with popular providers like Novita, OpenAI, Anthropic, and more.

Git Provider Configuration

Choose and configure your preferred Git provider. For basic token-based authentication, you only need to set the webhook URL:

For token-based authentication, you only need to configure the webhook URL. The other variables are required only if you want to use OAuth for authentication.

# Required for token-based authentication
API_GITHUB_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/github/webhook"          # GitHub webhook URL (update with your API domain)

# Optional - Only needed if using OAuth
API_GITHUB_APP_ID=                           # GitHub App ID
API_GITHUB_CLIENT_SECRET=                    # GitHub App Client Secret
API_GITHUB_PRIVATE_KEY=""                    # GitHub App Private Key
WEB_GITHUB_INSTALL_URL=""                    # GitHub App Installation URL
WEB_OAUTH_GITHUB_CLIENT_ID=""                # GitHub OAuth Client ID
WEB_OAUTH_GITHUB_CLIENT_SECRET=""            # GitHub OAuth Client Secret
GLOBAL_GITHUB_CLIENT_ID=
GLOBAL_GITHUB_REDIRECT_URI=

Never commit your .env file to version control. Keep your API keys and database credentials secure.

Run the Installation Script

Looking for more control? Check out our docker-compose file for manual deployment options.

Set the proper permissions for the installation script:

chmod +x scripts/install.sh

Run the script:

./scripts/install.sh

What the Installer Does

Our installer automates several important steps:

Verifies Docker installation
Creates networks for Kodus services
Clones repositories and configures environment files
Runs docker-compose to start all services
Executes database migrations
Seeds initial data

🎉 Success! When complete, Kodus Orchestrator API and Web Application should be running on your machine. You can verify your installation by visiting http://localhost:3000 - you should see the Kodus Web Application interface.

Code Review features will not work yet unless you complete the reverse proxy setup. Without this configuration, external Git providers cannot send webhooks to your instance.

Setting Up a Reverse Proxy

To make your Kodus instance accessible from external systems (required for Code Review webhooks and public access), you’ll need to configure a reverse proxy with Nginx. Here’s a sample Nginx configuration for two subdomains:

# Server block for the Kodus Web Application
server {
    listen 80;
    server_name kodus-web.yourdomain.com; # Replace with your actual web app domain

    location / {
        proxy_pass http://localhost:3000; # Points to the Kodus Web App container
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

# Server block for the Kodus API (Orchestrator)
server {
    listen 80;
    server_name kodus-api.yourdomain.com; # Replace with your actual API domain

    location / {
        proxy_pass http://localhost:3001; # Points to the Kodus Orchestrator API container
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Save this configuration to /etc/nginx/sites-available/kodus (or a name of your choice, e.g., kodus-web and kodus-api as separate files if preferred) and create a symbolic link to enable it:

sudo ln -s /etc/nginx/sites-available/kodus /etc/nginx/sites-enabled/
sudo nginx -t  # Test the configuration
sudo systemctl reload nginx  # Apply the changes

Important Configuration Update for Reverse Proxy:After setting up the reverse proxy with kodus-web.yourdomain.com and kodus-api.yourdomain.com (or your chosen subdomains), you must ensure your .env file correctly reflects these public URLs. Specifically, verify:

WEB_HOSTNAME_API: Should be set to only the hostname of your public API (e.g., kodus-api.yourdomain.com), without any protocol (http:// or https://).
WEB_PORT_API: Should correspond to the public port your API is accessible on (typically 443 for HTTPS or 80 for HTTP). The scheme (http/https) used by the frontend to call the API will often be inferred from this port or hardcoded in the frontend logic to use HTTPS.
Webhook URLs (e.g., API_GITHUB_CODE_MANAGEMENT_WEBHOOK): Ensure these are updated in your .env file to use your full public API domain including the scheme (e.g., https://kodus-api.yourdomain.com/webhooks/github).

Failure to update these correctly may result in authentication issues, inability for the web application to connect to the API, or malfunctioning webhooks.

Post-Installation Guide

After successfully deploying Kodus on your VM, follow these steps to get the most out of your installation:

Enabling SSL (Recommended)

For production deployments, we strongly recommend setting up SSL with Let’s Encrypt:

# Install Certbot for Let's Encrypt
sudo apt-get update
sudo apt-get install certbot python3-certbot-nginx

# Obtain and install certificates for both domains
sudo certbot --nginx -d kodus-web.yourdomain.com -d kodus-api.yourdomain.com # Replace with your actual domains

This will automatically configure your Nginx setup to use HTTPS and redirect HTTP traffic for both subdomains.

Completing Initial Setup

Once you access the web interface for the first time, you’ll need to:

Create your admin account - This will be the first user with full system access
Configure your Git provider - Connect GitHub, GitLab, or Bitbucket following the on-screen instructions
Select repositories for analysis - Choose which code repositories Kody will review

For detailed steps on the initial configuration process, refer to our Getting Started Guide.

Updating Kodus

To update your Kodus installation to the latest version:

# Navigate to your Kodus installation directory
cd kodus-installer

# Pull the latest changes from the repository
git pull

# Pull the latest Docker images
docker-compose pull

# Restart the services with the new images
docker-compose up -d

Monitoring Your Installation

You can monitor your Kodus installation using the following tools:

# Check container status
docker-compose ps

# View real-time logs from all services
docker-compose logs -f

# Monitor system resource usage
docker stats

Accessing Service Logs

When troubleshooting or monitoring your Kodus installation, you may need to access service logs:

Core Services Logs

# Kodus Web logs
docker logs kodus-web-prod

# Orchestrator logs
docker logs kodus-orchestrator-prod

# Access log files directly from orchestrator
docker exec -it kodus-orchestrator-prod ls /app/logs
```  </Accordion>

<Accordion title="Database Logs">
```bash
# PostgreSQL logs
docker logs db_kodus_postgres

# MongoDB logs
docker logs db_kodus_mongodb

Infrastructure Service Logs

# RabbitMQ logs
docker logs rabbitmq-prod

# Access RabbitMQ Management Console
# Available at http://localhost:15672 (default credentials in your .env file)

# Prometheus logs (if configured)
docker logs prometheus-prod

# Grafana logs (if configured)
docker logs grafana-prod

Troubleshooting Common Issues

Web Interface Not Accessible

Git Webhook Connection Errors

Database Connection Issues

Installation Script Fails

Get help with our community

Join our community to get help with your deployment.

Concepts

Local Quickstarts

Deploy Kodus

Git providers configuration

Generic Virtual Machine

System Requirements

Domain Name Setup (Optional)

Get the Kodus Installer

Configure Environment Variables

Deployment Process

Need help?

LLM Integration Settings

Model Configuration Guides

Git Provider Configuration

Run the Installation Script

What the Installer Does

Setting Up a Reverse Proxy

Post-Installation Guide

Enabling SSL (Recommended)

Completing Initial Setup

Updating Kodus

Monitoring Your Installation

Accessing Service Logs

Troubleshooting Common Issues

Get help with our community

Concepts

Local Quickstarts

Deploy Kodus

Git providers configuration

​System Requirements

​Domain Name Setup (Optional)

​Get the Kodus Installer

​Configure Environment Variables

​Deployment Process

Need help?

​LLM Integration Settings

Model Configuration Guides

​Git Provider Configuration

​Run the Installation Script

​What the Installer Does

​Setting Up a Reverse Proxy

​Post-Installation Guide

​Enabling SSL (Recommended)

​Completing Initial Setup

​Updating Kodus

​Monitoring Your Installation

​Accessing Service Logs

​Troubleshooting Common Issues

Get help with our community

System Requirements

Domain Name Setup (Optional)

Get the Kodus Installer

Configure Environment Variables

Deployment Process

LLM Integration Settings

Git Provider Configuration

Run the Installation Script

What the Installer Does

Setting Up a Reverse Proxy

Post-Installation Guide

Enabling SSL (Recommended)

Completing Initial Setup

Updating Kodus

Monitoring Your Installation

Accessing Service Logs

Troubleshooting Common Issues