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 kotomiThe volume keeps the comment database across restarts. Or run it with Go 1.24 or newer:
$ go run cmd/main.goCheck 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>| Option | Default | What it does |
|---|---|---|
baseUrl | required | URL of your Kotomi server. |
siteId | required | The site ID from the admin panel. |
pageId | required | A unique ID for the page. |
container | #kotomi-comments | CSS selector of the element to render into. |
theme | light | light or dark. |
enableReactions | true | Show emoji reactions. |
enableReplies | true | Allow threaded replies. |
jwtToken | null | Token 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:
| Variable | Default | What it does |
|---|---|---|
PORT | 8080 | Port the server listens on. |
DB_PATH | ./kotomi.db | Path of the SQLite database file. |
DB_PROVIDER | SQLite | Set to firestore to store data in Firestore. |
FIRESTORE_PROJECT_ID | none | Google 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_KEY | none | Enables 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.