Deployment

Running Koor in local, LAN, and cloud environments.

Tier 1: Local (Single Machine)

The simplest setup. No configuration needed.

./koor-server

All agents and tools run on the same machine and connect to localhost. This is the default for solo development.

Tier 2: LAN (Team / Multi-Machine)

Bind to a network interface and enable authentication.

./koor-server --bind 0.0.0.0:9800 --auth-token secret123

Or via environment variables:

export KOOR_BIND=0.0.0.0:9800
export KOOR_AUTH_TOKEN=secret123
./koor-server

Configure agents on other machines:

koor-cli config set server http://192.168.1.100:9800
koor-cli config set token secret123

LAN considerations:

Tier 3: Cloud / Remote

For remote deployments, add TLS termination in front of Koor.

With a Reverse Proxy (nginx)

server {
    listen 443 ssl;
    server_name koor.example.com;

    ssl_certificate /etc/ssl/certs/koor.pem;
    ssl_certificate_key /etc/ssl/private/koor.key;

    location / {
        proxy_pass http://127.0.0.1:9800;
        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;
    }
}

The Upgrade and Connection headers are needed for WebSocket event subscriptions.

Docker

Example Dockerfile:

FROM golang:1.21-alpine AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /koor-server ./cmd/koor-server
RUN CGO_ENABLED=0 go build -o /koor-cli ./cmd/koor-cli

FROM alpine:3.19
COPY --from=build /koor-server /usr/local/bin/koor-server
COPY --from=build /koor-cli /usr/local/bin/koor-cli
EXPOSE 9800 9847
VOLUME /data
CMD ["koor-server", "--data-dir", "/data", "--bind", "0.0.0.0:9800", "--dashboard-bind", "0.0.0.0:9847"]

Run:

docker build -t koor .
docker run -d -p 9800:9800 -p 9847:9847 -v koor-data:/data -e KOOR_AUTH_TOKEN=secret123 koor

systemd (Linux)

Create /etc/systemd/system/koor.service:

[Unit]
Description=Koor Coordination Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/koor-server --bind 0.0.0.0:9800 --data-dir /var/lib/koor --auth-token ${AUTH_TOKEN}
EnvironmentFile=/etc/koor/env
Restart=on-failure
RestartSec=5
User=koor
Group=koor

[Install]
WantedBy=multi-user.target

Create /etc/koor/env:

AUTH_TOKEN=your-secret-token

Enable and start:

sudo useradd -r -s /sbin/nologin koor
sudo mkdir -p /var/lib/koor
sudo chown koor:koor /var/lib/koor
sudo systemctl enable koor
sudo systemctl start koor

Windows Service

Use a service wrapper like NSSM or WinSW:

nssm install Koor "C:\koor\koor-server.exe" "--bind" "0.0.0.0:9800" "--data-dir" "C:\koor\data" "--auth-token" "secret123"
nssm start Koor

Data Backup

The database is a single SQLite file at {data_dir}/data.db. To back up:

# While the server is running (WAL mode supports hot backups):
cp ./data.db ./data.db.backup
cp ./data.db-wal ./data.db-wal.backup

Or stop the server and copy data.db alone (the WAL is merged on clean shutdown).

Resource Usage

Koor is lightweight: