How to Configure an Nginx Reverse Proxy with WebSockets for Kodi Chorus2

This tutorial details how to configure Nginx as a secure reverse proxy for Kodi's Chorus2 web interface, enabling full remote media playback control over HTTPS under a subpath (e.g., https://domain.com/kodi/).

Before configuring Nginx, enable the Kodi Web Server in Settings → Services → Control and set a secure username and password, as documented in the Kodi Web Interface Wiki.

The Nginx URI Normalization Challenge

Kodi Chorus2 requires two distinct routing configurations:

1. WebSocket JSON-RPC (port 9090): Real-time playback status and control events route through /jsonrpc without path prefixing.
2. Web Assets & Album Art (port 10080 / 8080): Chorus2 fetches album artwork and movie posters using dynamic queries. Under Nginx's proxy_pass specification, naive subpath proxying will corrupt the image query string unless the normalized request URI is explicitly matched and forwarded.

Nginx Configuration (/etc/nginx/sites-available/kodi.conf)

Add the following location blocks to your Nginx HTTPS server block:

## Kodi Reverse Proxy Configuration

# 1) WebSocket channel for JSON-RPC
location ^~ /jsonrpc {
    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_read_timeout 360s;
    proxy_pass         http://10.10.1.5:9090;
}

# 2) Redirect bare /kodi to canonical /kodi/
location = /kodi {
    return 301 /kodi/;
}

# 3) Proxy Chorus2 web interface and strip /kodi prefix
location /kodi/ {
    if ($request_uri ~ "^/kodi(?/[^?]*)") {
        set $new_path $after;
    }

    proxy_cache        off;
    proxy_set_header   Host      $host;
    proxy_set_header   X-Real-IP $remote_addr;
    proxy_read_timeout 300s;

    proxy_pass         http://10.10.1.5:10080$new_path$is_args$args;
}

Test your configuration and reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

In Chorus2 settings (in your browser), enable reverse proxy mode and set the port to 443. Album art, audio streaming, and WebSocket playback controls will now operate flawlessly.