Multiple Sites & Sub-URI

Multiple Sites

Isso is designed to serve comments for a single website and therefore stores comments for a relative URL. This is done to support HTTP, HTTPS and even domain transfers without manual intervention. You can chain Isso to support multiple websites on different domains.

The following example uses gunicorn as WSGI server ( you can use uWSGI as well). Let’s say you maintain two websites, like foo.example and other.bar:

; /etc/isso.d/foo.example.cfg
[general]
name = foo
host = http://foo.example/
dbpath = /var/lib/isso/foo.example.db

; /etc/isso.d/other.bar.cfg
[general]
name = bar
host = http://other.bar/
dbpath = /var/lib/isso/other.bar.db

Then you run Isso with gunicorn (separate multiple configuration files by semicolon):

$ export ISSO_SETTINGS="/etc/isso.d/foo.example.cfg;/etc/isso.d/other.bar.cfg"
$ gunicorn isso.dispatch -b localhost:8080

In your webserver configuration, proxy Isso as usual:

server {
    listen [::]:80;
    server_name comments.example;

    location / {
        proxy_pass http://localhost:8080;
    }
}

When you now visit http://comments.example/, you will see your different Isso configuration separated by /name.

$ curl http://comments.example/
/foo
/bar

Just embed the JavaScript including the new relative path, e.g. http://comments.example/foo/js/embed.min.js. Make sure, you don’t mix the URLs on both sites as it will most likely cause CORS-related errors.

Note

Multi-site support in Docker

Multi-site support (using multiple config files separated by semicolons in ISSO_SETTINGS) requires running Isso with the isso.dispatch entry point, not isso.run.

The official Docker image runs Isso with isso.run by default, which only supports a single config file.

To enable multi-site in Docker, override the default command to use isso.dispatch. For example, in your docker-compose.yml:

services:
  isso-comments:
    image: ghcr.io/isso-comments/isso:release
    environment:
      ISSO_SETTINGS: "/config/example1.com.cfg;/config/example2.com.cfg"
    command: ["isso.dispatch"]
    # ... other options ...

This will enable multi-site support as described above.

Sub-URI

You can run Isso on the same domain as your website, which circumvents issues originating from CORS. Also, privacy-protecting browser addons such as Request Policy wont block comments.

server {
    listen       [::]:80;
    listen       [::]:443 ssl;
    server_name  example.tld;
    root         /var/www/example.tld;

    location /isso {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Script-Name /isso;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://localhost:8080;
    }
}

Important

When using a sub-URI setup (e.g., serving Isso at /isso or any other path), you must ensure the Isso client can correctly detect the API endpoint.

Recommended approach: Explicitly set the data-isso attribute in your embed script to match your sub-URI:

<script data-isso="/isso" src="/isso/js/embed.min.js"></script>

This ensures all API requests are correctly prefixed with your sub-URI (e.g., /isso/new, /isso/config).

If you omit this attribute, Isso will attempt to auto-detect the endpoint from the script’s src path, which may fail or cause requests to be sent to the root path (/) instead of your sub-URI. This can result in broken comment functionality or 404 errors.

Now, the website integration is just as described in Quickstart but with a different location.