openkor-installer

This repository contains the Docker Compose setup file that brings up all components of the OpenKor platform with a single command.

Architecture

                        ┌─────────────┐
                        │   korapi    │  :8080  (API Gateway)
                        └──────┬──────┘
               ┌───────────────┼───────────────┐
               ▼               ▼               ▼
         ┌──────────┐   ┌──────────┐   ┌──────────┐
         │ korauth  │   │  korvm   │   │  korvol  │
         │  :8081   │   │  :8082   │   │  :8083   │
         └────┬─────┘   └────┬─────┘   └──────────┘
              │              │
        ┌─────┴──────────────┴─────┐
        │                          │
   ┌────▼─────┐             ┌──────▼───┐
   │ postgres │             │  redis   │
   │  :5432   │             │  :6379   │
   └──────────┘             └──────────┘

Service	Port	Description
korapi	8080	Main API gateway, routes all incoming requests
korauth	8081	Authentication and JWKS management
korvm	8082	Virtual machine management (libvirt/KVM)
postgres	5432	Primary database
redis	6379	Cache and message queue

Requirements

• Docker >= 24.0
• Docker Compose >= 2.20
• A Linux host with KVM enabled (required for korvm)
  • lsmod | grep kvm output should show kvm_intel or kvm_amd
  • User must be in the kvm group for /dev/kvm access: sudo usermod -aG kvm $USER
• libvirt must be installed and running (required for korvm)
  • /var/run/libvirt/libvirt-sock must exist

Directory Structure

This repository expects the following sibling directories:

projects/
├── openkor-installer/   # this repo
│   └── docker-compose.yml
├── korauth/
│   ├── Dockerfile
│   ├── .env             # optional
│   └── keys/            # JWT signing keys
├── korvm/
│   ├── Dockerfile
│   └── .env             # optional
├── korapi/
│   └── Dockerfile
└── korvol/
    └── Dockerfile

Installation

1. Clone the repositories

git clone <korauth-repo-url> ../korauth
git clone <korvm-repo-url>   ../korvm
git clone <korapi-repo-url>  ../korapi
git clone <korvol-repo-url>  ../korvol

2. Generate JWT keys for korauth

mkdir -p ../korauth/keys
# Generate RSA key pair
openssl genrsa -out ../korauth/keys/private.pem 2048
openssl rsa -in ../korauth/keys/private.pem -pubout -out ../korauth/keys/public.pem

3. (Optional) Customize environment variables

For production, change the database password and other sensitive variables:

../korauth/.env

# Example — variable names depend on the service source code
JWT_ISSUER=https://auth.example.com

../korvm/.env

# korvm-specific configuration

Make sure to change POSTGRES_PASSWORD: changeme in docker-compose.yml before deploying to production.

4. Start the services

docker compose up -d

To wait until all services pass their health checks:

docker compose up -d --wait

5. Verify the installation

curl http://localhost:8080/healthz

A 200 OK response indicates all services are up and running.

Common Commands

# Stream all logs live
docker compose logs -f

# Stream logs for a specific service
docker compose logs -f korapi

# Stop services (data is preserved)
docker compose down

# Stop services and delete all data
docker compose down -v

# Restart a single service
docker compose restart korauth

# Rebuild all images from scratch
docker compose build --no-cache

# Show the status of running services
docker compose ps

Troubleshooting

korvm won't start — /dev/kvm not found

ls -la /dev/kvm
# If it doesn't exist:
sudo modprobe kvm_intel   # Intel CPU
sudo modprobe kvm_amd     # AMD CPU

korvm won't start — libvirt socket not found

sudo systemctl start libvirtd
ls -la /var/run/libvirt/libvirt-sock

Database connection error

Wait for the postgres service to reach the healthy state. The korauth and korvm services depend on it via depends_on, but if issues persist after a manual restart:

docker compose restart korauth korvm

Port conflict

If you suspect another process is using the required ports (8080, 8081, 8082, 5432, 6379):

lsof -i :8080

Network and Data Volumes

• All services run on a bridge network named openkor; only mapped ports are accessible from the outside.
• postgres_data — database files
• image_pool — virtual machine disk images used by korvm

Running docker compose down -v will permanently delete these volumes.