What better first post can there be but one about how to configure the Isso commenting system with Caddy in a subdirectory? After all, that's the reason I set up this blog.

I will assume a few things here.

• You've got a Caddy webserver running with one website, and your own domain.
  • One Isso instance on multiple websites is supported, but not the subject of this post.
• You're using a static site generator like Zola with a blogging theme and you want to have comments …
• … but you don't want to use Disqus or any other type of privacy risk for this.
• While you're at it, you don't want to embed any external dependency at all, i.e., you must be able to self-host it.

I opened my Matrix client one day to skim the recent messages and there happened to be one, one, little message tersely telling people "hey I've set up this nice commenting system for my static blog" with a link to Isso – that is how I found out about it.

Installation

As a user of Arch Linux the installation was straightforward: Use the AUR package. For any other distribution, the documentation has a section on installing it via PyPI or Docker (apart from installing it from source). Yes, it is a Python program – depending on who you ask it's fortunate or not. :)

One thing I would recommend if installed via PyPI or AUR is to additionally create a separate (system) user for Isso (like you'd hopefully do with any other webapp). Docker users don't need this, though, it's isolated already.

Isso configuration

Once that's done, the only thing we're going to edit is /etc/isso.cfg. The format is INI and all the options are documented. For the purpose of this article this is what's important to set:

general

• host = https://fossfed.eu/. The URL to your website. Mind the trailing /. Since Caddy by default redirects http://, setting it additionally makes no sense unless you changed this behavior.

server

• listen. Default is localhost:8080. UNIX sockets are supported, and probably a better choice if not using Docker.
• public-endpoint = https://fossfed.eu/comments. The request path people will request the Isso JS from. This time, mind the missing trailing slash.
• trusted-proxies = 127.0.0.1. Caddy will reverse proxy requests, therefore, some headers will be inaccurate. Tell Isso 127.0.0.1 is not a user, but a middleman.

Caddy configuration

What we're here for. In the server block for your domain, handle requests to /comments/ separately by reverse_proxying them to the listen address, adding one header containing your subdirectory (needed) and optionally removing another (strips version information on Python and Werkzeug/BaseHTTP), while serving files otherwise:

fossfed.eu {
    root * <some path>
    reverse_proxy /comments/* {
        to localhost:8080
        header_up X-Script-Name /comments
        header_down -Server
    }
    file_server
}

Client configuration

Also documented. For the subdirectory use case, these options are necessary:

• data-isso=/comments/. Mind the preceding and trailing /. Isso may detect this by itself, but I don't trust reverse-proxied apps served on a subdirectory to do this since most of them expect to be served on /. See also The subdirectory problem, or why can't I reverse proxy into a subfolder?.
• src=/comments/js/embed.min.js. Path to the Isso JS.

Finalization

Start the Isso service or container, reload or restart Caddy and embed the JS into your template. Build your site – and let the troubleshooting begin, I guess. Why don't you use the comments section below for that? :)