​
How Groq works

Groq Cloud provides fast LLM inference with OpenAI-compatible APIs. Built for speed and simplicity, Groq offers ultra-fast inference for popular models like Llama, Deepseek, and more. The platform is designed to be simple to integrate and easy to scale, making it perfect for production applications.

We recommend good coding models with high context windows and fast inference.

For the most updated information, please visit Groq’s models page.

ModelContext WindowSpeed
Llama 3.3 70B Versatile recommended~128k tokensUltra Fast
Deepseek R1 Distill Llama 70B~128k tokensUltra Fast
Llama 3.1 70B Versatile~128k tokensUltra Fast

​
Creating API Key

Groq Cloud Account is required to create API Key.

Go directly to Groq’s API Keys page to create a new API Key.

Or, follow these steps:

  1. Go to Groq Console
  2. Sign in or create your account
  3. Navigate to “API Keys” in the top navigation
  4. Click on “Create API Key” button
  5. Give it a name like ‘Kodus’ or any descriptive name
  6. Copy the API Key and save it somewhere safe

Only team owners or users with the developer role may create or manage API keys in Groq.

​
How to use

​
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.

​
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

​
Configure Groq in Environment File

Edit your .env file and configure the core settings. For LLM Integration, use Groq in Fixed Mode:

# Core System Settings (update with your domains)
WEB_HOSTNAME_API="kodus-api.yourdomain.com"    
WEB_PORT_API=443                               
NEXTAUTH_URL="https://kodus-web.yourdomain.com"

# Security Keys (generate with openssl commands above)
WEB_NEXTAUTH_SECRET="your-generated-secret"
WEB_JWT_SECRET_KEY="your-generated-secret"
API_CRYPTO_KEY="your-generated-hex-key"
API_JWT_SECRET="your-generated-secret"
API_JWT_REFRESHSECRET="your-generated-secret"

# Database Configuration
API_PG_DB_PASSWORD="your-secure-db-password"
API_MG_DB_PASSWORD="your-secure-db-password"

# Groq Configuration (Fixed Mode) 
API_LLM_PROVIDER_MODEL="llama-3.3-70b-versatile"             # Choose your preferred model
API_OPENAI_FORCE_BASE_URL="https://api.groq.com/openai/v1"   # Groq API URL
API_OPEN_AI_API_KEY="your-groq-api-key"                      # Your Groq API Key

# Git Provider Webhooks (choose your provider)
API_GITHUB_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/github/webhook"
# or API_GITLAB_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/gitlab/webhook"
# or GLOBAL_BITBUCKET_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/bitbucket/webhook"

Fixed Mode is ideal for Groq because it provides OpenAI-compatible APIs with ultra-fast inference. This gives you the best performance with simple configuration.

​
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.

​
Set Up Reverse Proxy (For Production)

For webhooks and external access, configure Nginx:

# Web App (port 3000)
server {
    listen 80;
    server_name kodus-web.yourdomain.com;
    location / {
        proxy_pass http://localhost:3000;
        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;
    }
}

# API (port 3001)  
server {
    listen 80;
    server_name kodus-api.yourdomain.com;
    location / {
        proxy_pass http://localhost:3001;
        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;
    }
}

​
Verify Groq Integration

Além da verificação básica da instalação, confirme que o Groq está funcionando:

# Verify Groq API connection specifically
docker logs kodus-orchestrator-prod | grep -i groq

For detailed information about SSL setup, monitoring, and advanced configurations, see our complete deployment guide.

​
Troubleshooting