Isso Documentation

Isso is a lightweight, Python and JavaScript-based commenting server designed as a drop-in replacement for Disqus. Key features include:

• Markdown Support: Users can write comments in Markdown. Users can edit or delete their own comments (default window is 15 minutes).
• SQLite Backend: Uses SQLite for storage, optimized for comment data.
• Migration Tools: Supports importing comments from Disqus and WordPress.
• Lightweight Client: A single 65kB (20kB gzipped) JavaScript file for embedding.

Use the Makefile to generate and view the code coverage report for the server.

make coverage

After installing Isso from source, you can run a development server locally. The server will be available at localhost:8080. For convenience, the development version uses embed.dev.js with source maps, which allows for easier debugging in browser developer tools (e.g., showing actual source code lines in console traces).

To start the server, activate your virtual environment and run the isso command with the development configuration file.

$ virtualenv --download .venv
$ source .venv/bin/activate
(.venv) $ isso -c contrib/isso-dev.cfg run

To release a new version of Isso, follow these steps to ensure tests pass, version metadata is updated, and the package is uploaded to PyPI:

1. Run tests: make test
2. Update the version number in setup.py and CHANGES.rst.
3. Commit the version changes: git commit -m "Preparing ${VERSION}" setup.py CHANGES.rst (replace ${VERSION} with your actual version).
4. Tag the release: git tag -as ${VERSION}.
5. Initialize the environment: make init all.
6. Build the source distribution: python3 setup.py sdist.
7. Upload to PyPI using twine: twine upload --sign dist/isso-${VERSION}.tar.gz.

make test
# Update setup.py and CHANGES.rst
git commit -m "Preparing ${VERSION}" setup.py CHANGES.rst
git tag -as ${VERSION}
make init all
python3 setup.py sdist
twine upload --sign dist/isso-${VERSION}.tar.gz

To comply with GDPR, you can periodically anonymize commenter IP addresses by setting them to 127.0.0.1. Add the following command to your crontab to run it weekly:

@weekly /usr/bin/sqlite3 /path/to/isso/comments.db 'UPDATE comments SET remote_addr = "127.0.0.1";'

To upgrade your existing Isso installation, activate your virtual environment and use pip upgrade:

source /opt/isso/bin/activate
pip install --upgrade isso

Isso uses an INI-style text file for configuration. You can specify a custom configuration file using the -c flag or by setting the ISSO_SETTINGS environment variable.

A basic configuration requires a [general] section with a dbpath and a host, and a [server] section with a listen address.

[general]
dbpath = /var/lib/isso/comments.db
host = https://example.tld/

[server]
listen = http://localhost:1234/

# Using the -c flag
$ isso -c /path/to/isso.cfg

# Using the ISSO_SETTINGS environment variable
$ env ISSO_SETTINGS=/path/to/isso.cfg$ isso

Install flake8 and use the Makefile to check the Python code style.

pip install flake8
make flakes

To avoid CORS issues and prevent privacy-protecting browser extensions from blocking comments, you can run Isso on the same domain as your website using a sub-URI (e.g., /isso).

When using Nginx as a reverse proxy, you must set the X-Script-Name header to your chosen sub-URI path so Isso can correctly handle routing.

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;
    }
}

To begin using Isso, follow these steps in order:

1. Install Isso: Refer to the installation documentation to set up the server.
2. Follow the Quickstart guide: Use the quickstart guide to perform an initial setup and verify the installation.
3. Troubleshoot: If you encounter issues, consult the troubleshooting guide.

Isso is a lightweight commenting server that supports anonymous comments, maintains identity, and is designed for easy integration into static websites using JavaScript and CORS.