Tools / Comments for static sites

Kotomi

Comments and reactions for pages that have no backend. Run one service, embed a widget, moderate from an admin panel. Your readers' words stay on your own server.

Status

Kotomi is in beta. It works end to end, but expect changes before 1.0 and keep backups of your database.

Run the server

Kotomi is one Go service with an SQLite database, so there is nothing else to provision. With Docker:

$ git clone https://github.com/saasuke-labs/kotomi
$ cd kotomi
$ docker build -t kotomi .
$ docker run -p 8080:8080 -v kotomi-data:/app/data kotomi

The volume keeps the comment database across restarts. Or run it with Go 1.24 or newer:

$ go run cmd/main.go

Check that it is up:

$ curl http://localhost:8080/healthz

Create a site

Open http://localhost:8080/admin and sign in. The admin panel uses Auth0, which you configure with environment variables; the admin panel guide walks through it.

Create a site and note its ID. One Kotomi instance can serve several sites, each with its own pages, reactions and moderation settings.

Embed the widget

Add the stylesheet, a container and the script to your page template. The widget has no dependencies.

<link rel="stylesheet" href="https://comments.example.com/static/kotomi.css" />

<div id="kotomi-comments"></div>

<script src="https://comments.example.com/static/kotomi.js"></script>
<script>
  new Kotomi({
    baseUrl: "https://comments.example.com",
    siteId: "my-blog",
    pageId: "hello-world",
  }).render();
</script>
OptionDefaultWhat it does
baseUrlrequiredURL of your Kotomi server.
siteIdrequiredThe site ID from the admin panel.
pageIdrequiredA unique ID for the page.
container#kotomi-commentsCSS selector of the element to render into.
themelightlight or dark.
enableReactionstrueShow emoji reactions.
enableRepliestrueAllow threaded replies.
jwtTokennullToken for signed-in readers.

Moderation

Every comment has a status: pending, approved or rejected. From the admin panel you can filter by status, approve or reject in one click and delete spam.

Automatic moderation is optional. With an OpenAI API key set, each comment is scored for spam, offensive language, aggressive tone and off-topic content, then handled by thresholds you set per site:

  • Low scores are approved automatically.
  • Middle scores wait for manual review.
  • High scores are rejected automatically.

Without a key, a built-in rule-based moderator is used.

Configuration

Kotomi is configured with environment variables. The common ones:

VariableDefaultWhat it does
PORT8080Port the server listens on.
DB_PATH./kotomi.dbPath of the SQLite database file.
DB_PROVIDERSQLiteSet to firestore to store data in Firestore.
FIRESTORE_PROJECT_IDnoneGoogle Cloud project, when using Firestore.
CORS_ALLOWED_ORIGINS*Comma-separated origins allowed to call the API. Set this to your site's origin in production.
OPENAI_API_KEYnoneEnables AI-assisted moderation.

Rate limits, email notifications, export and import, and logging are covered in the README.

API

The widget talks to a REST API that you can call directly. Readers are authenticated with JWTs that your own site issues. In development mode the server hosts interactive documentation at /swagger/index.html.

With Gengo

Add the widget to the page template of a Gengo site and use a value from the page metadata as pageId. The five-minute quick start has the full template. Gengo can also read comments at build time through its data sources.

Guides

Using Kotomi at work?

Saasuke Labs is independent and maintained in the open. Sponsorship pays for maintenance, documentation and releases.