Generic Virtual Machine
Deploy Kodus on a Generic Virtual Machine.
System Requirements
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.
Deployment Process
Need help?
Schedule a call with our founder to get help with your deployment.
1. 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.
2. Get the Kodus Installer
Clone our installer repository:
3. Configure Environment Variables
First, copy the example environment file:
Generate secure keys for the required environment variables using:
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)
- CODEMANAGEMENT_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:
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.
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
This is the simplest mode and recommended for self-hosted installations. You only need to configure a single LLM model.
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
This mode uses multiple LLM models to achieve the best possible results. Requires more configuration but offers the highest quality analysis.
This mode offers the best quality because:
- Uses multiple specialized models
- Our pipeline is optimized to extract the best from each model
- Ideal for enterprise installations prioritizing quality
API Keys Resources
When configuring your environment variables, you’ll need API keys for AI providers. Use these official resources:
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.
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.
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.
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.
Never commit your .env
file to version control. Keep your API keys and
database credentials secure.
4. 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:
Run the script:
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:
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:
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://
orhttps://
).WEB_PORT_API
: Should correspond to the public port your API is accessible on (typically443
for HTTPS or80
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:
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:
Monitoring Your Installation
You can monitor your Kodus installation using the following tools:
Accessing Service Logs
When troubleshooting or monitoring your Kodus installation, you may need to access service logs:
Troubleshooting Common Issues
Get help with our community
Join our community to get help with your deployment.