Skip to main content
Optional Step: Only needed if you will not use any loadbalancer or proxy server.
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
server {
    listen 80;
    server_name kodus-api.yourdomain.com; # Replace with your actual API domain

    location ~ ^/(github|gitlab|bitbucket|azure-repos)/webhook {
        proxy_pass http://localhost:3332; # Points to the Kodus Webhooks service
        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;
    }

    location / {
        proxy_pass http://localhost:3001; # Points to the Kodus API service
        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/github/webhook).
Failure to update these correctly may result in authentication issues, inability for the web application to connect to the API, or malfunctioning webhooks.
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.