Skip to content
Klutch.sh Docs

Deploying Isso

Introduction

Isso is a lightweight, self-hosted commenting server designed for static websites and blogs. Written in Python and using SQLite for storage, Isso provides a privacy-respecting alternative to third-party commenting services like Disqus. The super-light JavaScript client loads quickly without bloating your pages.

Isso supports Markdown formatting, comment threading, upvoting/downvoting, and email notifications while keeping your visitors’ data under your control. The minimalist design focuses on doing one thing well: enabling conversations on your content without compromising privacy or performance.

Key highlights of Isso:

  • Privacy-First: No tracking, no analytics, no third-party data sharing
  • Lightweight Client: Minimal JavaScript footprint for fast page loads
  • Markdown Support: Rich text formatting with Markdown syntax
  • Threaded Comments: Nested replies for organized discussions
  • Voting System: Upvote and downvote comments
  • Spam Protection: Built-in spam mitigation with rate limiting
  • Email Notifications: Notify authors of new comments
  • Gravatar Support: Optional avatar integration
  • SQLite Storage: Simple, file-based database
  • Import Support: Migrate comments from Disqus and WordPress
  • CORS Support: Secure cross-origin embedding
  • Open Source: MIT licensed with active community

This guide walks through deploying Isso on Klutch.sh using Docker, embedding comments on your static site, and configuring the server for production use.

Why Deploy Isso on Klutch.sh

Deploying Isso on Klutch.sh provides several advantages for adding comments to your static sites:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Isso without complex server configuration. Push to GitHub, and your comment server deploys automatically.

Persistent Storage: Attach persistent volumes for your SQLite database. Your comments survive container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, essential for secure comment submission from HTTPS sites.

GitHub Integration: Connect your configuration repository for automated deployments when you update settings.

Scalable Resources: Allocate CPU and memory based on expected comment traffic. Start small and scale as your site grows.

Environment Variable Management: Securely store configuration through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom subdomain for your commenting service.

Always-On Availability: Your comment server remains accessible 24/7.

Prerequisites

Before deploying Isso on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your Isso configuration
  • A static website or blog where you want to add comments
  • Basic familiarity with Docker and containerization concepts
  • (Optional) A custom domain or subdomain for your Isso instance

Understanding Isso Architecture

Isso follows a simple client-server architecture:

Python Server: The backend handles comment storage, retrieval, moderation, and email notifications. It exposes a REST API for the JavaScript client.

SQLite Database: All comments are stored in a single SQLite file, making backup and migration simple.

JavaScript Client: A lightweight script embedded on your pages that renders the comment widget and handles user interactions.

Configuration File: A simple INI-style configuration file controls all server behavior.

Preparing Your Repository

To deploy Isso on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

isso-deploy/
├── Dockerfile
├── isso.conf
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/isso-comments/isso:release


# Copy configuration file
COPY isso.conf /config/isso.conf


# Create database directory
RUN mkdir -p /db


# Environment variables
ENV ISSO_SETTINGS=/config/isso.conf


# Expose Isso port
EXPOSE 8080


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/info || exit 1

Creating the Configuration File

Create an isso.conf file:

[general]
; Database location - must match volume mount
dbpath = /db/comments.db


; Your website's URL(s) - comments are only accepted from these hosts
host = https://yourblog.com


; Log level
log-file = /dev/stdout


[moderation]
; Enable comment moderation
enabled = false


; Require comment approval
; approve-if-email-previously-approved = true


[server]
; Server listen address
listen = http://0.0.0.0:8080/


; Publicly accessible URL (set via environment or here)
public-endpoint = https://comments.yourblog.com


[guard]
; Rate limiting
enabled = true
ratelimit = 2
direct-reply = 3
reply-to-self = false
require-author = false
require-email = false


[markup]
; Allowed HTML elements
options = strikethrough, superscript, autolink
allowed-elements = a, blockquote, br, code, em, p, pre, strong, ul, ol, li
allowed-attributes = a href


[hash]
; Comment ID algorithm
algorithm = pbkdf2

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

VariableRequiredDefaultDescription
ISSO_HOSTYes-Allowed host(s) for comments (comma-separated)
ISSO_PUBLIC_ENDPOINTYes-Public URL where Isso is accessible
ISSO_DBPATHNo/db/comments.dbPath to SQLite database
ISSO_NOTIFYNo-Email notification settings
ISSO_SMTP_HOSTNo-SMTP server for notifications
ISSO_SMTP_PORTNo587SMTP port
ISSO_SMTP_USERNAMENo-SMTP username
ISSO_SMTP_PASSWORDNo-SMTP password

Deploying Isso on Klutch.sh

Once your repository is prepared, follow these steps to deploy Isso:

    Push Your Repository to GitHub

    Initialize your repository and push to GitHub:

    Terminal window
    git init
    git add Dockerfile isso.conf .dockerignore README.md
    git commit -m "Initial Isso deployment configuration"
    git remote add origin https://github.com/yourusername/isso-deploy.git
    git push -u origin main

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “isso” or “comments”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Isso Dockerfile.

    Configure HTTP Traffic

    In the deployment settings:

    • Select HTTP as the traffic type
    • Set the internal port to 8080

    Set Environment Variables (Optional)

    Override configuration via environment variables:

    VariableValue
    ISSO_HOSThttps://yourblog.com
    ISSO_PUBLIC_ENDPOINThttps://your-app-name.klutch.sh

    Attach Persistent Volumes

    Add persistent storage for the comment database:

    Mount PathRecommended SizePurpose
    /db1 GBSQLite database with all comments

    Deploy Your Application

    Click Deploy to start the build process. Klutch.sh will build and start your Isso server.

    Verify Deployment

    Once deployment completes, access https://your-app-name.klutch.sh/info to verify Isso is running.

Embedding Comments on Your Website

Adding the Script

Add the Isso client to your website’s HTML:

<!-- Isso comment section -->
<script data-isso="https://your-app-name.klutch.sh/"
        data-isso-css="true"
        data-isso-lang="en"
        data-isso-reply-to-self="false"
        data-isso-require-author="true"
        data-isso-require-email="false"
        data-isso-max-comments-top="10"
        data-isso-max-comments-nested="5"
        data-isso-reveal-on-click="5"
        data-isso-avatar="true"
        data-isso-avatar-bg="#f0f0f0"
        data-isso-vote="true"
        src="https://your-app-name.klutch.sh/js/embed.min.js">
</script>


<!-- Comment section placeholder -->
<section id="isso-thread">
    <noscript>JavaScript is required to view comments.</noscript>
</section>

Script Data Attributes

Configure the client with data attributes:

AttributeDefaultDescription
data-isso-URL of your Isso server
data-isso-csstrueInclude default CSS
data-isso-langenInterface language
data-isso-reply-to-selffalseAllow self-replies
data-isso-require-authorfalseRequire author name
data-isso-require-emailfalseRequire email address
data-isso-avatartrueShow avatars
data-isso-votetrueEnable voting

Custom Styling

Override default styles:

/* Comment container */
#isso-thread {
    font-family: system-ui, sans-serif;
}


/* Comment text */
.isso-comment .isso-text {
    color: #333;
}


/* Post button */
.isso-postbox .isso-post-action input {
    background-color: #0066cc;
}

Comment Moderation

Admin Interface

Access the admin at https://your-app-name.klutch.sh/admin:

  • Default password is empty (change immediately!)
  • Review pending comments
  • Delete or edit comments
  • View comment statistics

Setting Admin Password

Add to your isso.conf:

[admin]
enabled = true
password = your-secure-password

Email Moderation

Configure email notifications:

[general]
notify = smtp


[smtp]
host = smtp.example.com
port = 587
security = starttls
username = your@email.com
password = your-password
to = moderator@yourblog.com
from = comments@yourblog.com
timeout = 10

Migrating from Other Systems

From Disqus

Export and import Disqus comments:

  1. Export your Disqus comments as XML
  2. Use the import command:
    Terminal window
    isso -c isso.conf import disqus-export.xml

From WordPress

Import WordPress comments:

  1. Export WordPress comments as XML
  2. Use the import command:
    Terminal window
    isso -c isso.conf import wordpress-export.xml

Production Best Practices

Security Recommendations

  • Admin Password: Set a strong admin password
  • Host Restriction: Only allow comments from your domains
  • Rate Limiting: Keep rate limiting enabled
  • HTTPS Only: Ensure both your site and Isso use HTTPS
  • CORS Configuration: Properly configure allowed origins

Performance Optimization

  • Caching: Comments are already lightweight
  • CDN: Consider CDN for static assets if needed
  • Database Location: Keep database on persistent volume

Backup Strategy

  1. Database Backup: Regularly back up the SQLite file
  2. Simple Process: Just copy /db/comments.db
  3. Test Restores: Verify backups periodically

Troubleshooting Common Issues

CORS Errors

Symptoms: Comments don’t load, console shows CORS errors.

Solutions:

  • Verify your site URL is in the host configuration
  • Check public-endpoint matches your Isso URL
  • Ensure both use HTTPS

Comments Not Saving

Symptoms: Comments appear to submit but don’t persist.

Solutions:

  • Check database file permissions
  • Verify persistent volume is mounted
  • Review server logs for errors

Widget Not Loading

Symptoms: Comment section is blank.

Solutions:

  • Verify the script src URL is correct
  • Check browser console for JavaScript errors
  • Ensure Isso server is running

Additional Resources

Conclusion

Deploying Isso on Klutch.sh gives you a lightweight, privacy-respecting commenting system for your static websites. The combination of Isso’s minimal footprint and Klutch.sh’s simple deployment means you can add comments to your blog or documentation in minutes.

With no third-party tracking, simple SQLite storage, and easy embedding, Isso on Klutch.sh provides the perfect commenting solution for privacy-conscious site owners who want full control over their visitors’ data.