Installation

Isso is a web application written in Python. If pip and virtualenv mean anything to you, continue with Install from PyPi. If you are running Debian/Ubuntu or Arch Linux, you can use Prebuilt Packages. If not, read the next section carefully.

Interludium: Python is not PHP

If you think hosting a web application written in Python is as easy as one written in PHP, you are wrong. Unlike for PHP, many Linux distribution use Python for internal tools. Your package manager already ships several python libraries, but most likely not all required by Isso (or in an up-to-date version – looking at you, Debian!).

That’s why most Python developers use the Python Package Index to get their dependencies. The most important rule to follow is to never install anything from PyPi as root. Not because of malicious software, but because you will break your system. pip is one tool to mess up your system. If you ever searched for an issue with Python/pip and Stackoverflow is suggesting you pip install --upgrade pip (as root of course!), you are doing it wrong. Why you should not use Python’s easy_install carelessly on Debian is worth the read.

Fortunately, Python has a way to install packages (both as root and as user) without interfering with your globally installed packages: virtualenv. Use this always if you are installing software unavailable in your favourite package manager.

# for Debian/Ubuntu
$ sudo apt-get install python3-setuptools python3-virtualenv python3-dev

# Fedora/Red Hat
$ sudo yum install python3-setuptools python3-virtualenv python3-devel

The next steps should be done as regular user, not as root (although possible but not recommended):

$ virtualenv --download /opt/isso
$ source /opt/isso/bin/activate

Note

This guide will refer to commands that need to run inside an activated virtualenv with the (.venv) $ prefix.

After calling source, you can now install packages from PyPi locally into this virtual environment. If you don’t like Isso anymore, you just rm -rf the folder. Inside this virtual environment, you may also execute the example commands from above to upgrade your Python Package Manager (although it barely makes sense), it is completely independent from your global system.

To use Isso installed in a virtual environment outside of the virtual environment, you just need to add /opt/isso/bin to your PATH or execute /opt/isso/bin/isso directly. It will launch Isso from within the virtual environment.

With a virtualenv active, you may now continue to Install from PyPi! Of course you may not need a virtualenv when you are running dedicated virtual machines or a shared host (e.g. Uberspace.de).

Install from PyPi

Requirements

  • Python 3.8+ (+ devel headers) and Virtualenv

  • SQLite 3.3.8 or later

  • a working C compiler

For Debian/Ubuntu just copy and paste to your terminal:

$ sudo apt-get install python3-dev python3-virtualenv sqlite3 build-essential

Similar for Fedora (and derivates):

$ sudo yum install python3-devel python3-virtualenv sqlite
$ sudo yum groupinstall “Development Tools”

Installation

Install Isso with pip, using the virtualenv set up before:

$ source /opt/isso/bin/activate
(.venv) $ pip install isso

For easier execution, you can symlink the executable to a location in your PATH.

$ ln -s /opt/isso/bin/isso /usr/local/bin/isso

Upgrade

To upgrade Isso, activate your virtual environment again, and run

$ source /opt/isso/bin/activate  # optional
(.venv) $ pip install --upgrade isso

Prebuilt Packages

  • Arch Linux: The isso AUR package (maintained by @HLFH) follows the latest stable release, while the isso-git package (maintained by @AlphaJack) always builds the latest commit from git.

  • Debian: The package was dropped in 2021 from the Debian repositories.

Using Docker

Assuming you have your configuration in /var/lib/isso, with dbpath=/db/comments.db and host set properly in isso.cfg, you have two options for running a Docker container:

a) Official Docker image

Attention

The Docker image tagging scheme for stable releases was changed from :latest to :release as of March 2024 (#970, #1012).

A Docker image with the latest stable release is provided at ghcr.io/isso-comments/isso:release, while isso:latest is rebuilt on every push to the master branch.

The maintainers recommend pinning the image to a release tag, e.g. isso:0.13.0.

$ docker pull ghcr.io/isso-comments/isso:release
$ mkdir -p config/ db/
$ cp contrib/isso.sample.cfg config/isso.cfg
# Set 'dbpath' to '/db/comments.db' and adjust 'host'
$ docker run -d --rm --name isso -p 127.0.0.1:8080:8080 \
    -v /var/lib/isso:/config -v /var/lib/isso:/db \
    ghcr.io/isso-comments/isso:release

b) Build a Docker image yourself

You can build a Docker image by running make docker, which will be tagged as isso:latest.

$ mkdir -p config/ db/
$ cp contrib/isso.sample.cfg config/isso.cfg
# Set 'dbpath' to '/db/comments.db' and adjust 'host'
$ docker run -d --rm --name isso -p 127.0.0.1:8080:8080 \
    -v $PWD/config:/config -v $PWD/db:/db \
    isso:latest

Then, you can use a reverse proxy to expose port 8080.

Install from Source

If you want to hack on Isso or track down issues, there’s an alternate way to set up Isso. It requires a lot more dependencies and effort:

  • Python 3.8+ (+ devel headers)

  • Virtualenv

  • SQLite 3.3.8 or later

  • a working C compiler (e.g. the gcc package)

  • Node.js, NPM - required for frontend

Get a fresh copy of Isso:

$ git clone https://github.com/isso-comments/isso.git
$ cd isso/

To create a virtual environment (recommended), run:

$ virtualenv --download .venv
$ source .venv/bin/activate

Install JavaScript modules using npm:

$ make init

Build JavaScript frontend code:

$ make js

Install Isso and its dependencies:

(.venv) $ pip install -e .  # -e = "editable" installation for development
(.venv) $ isso -c /path/to/isso.cfg run

Init scripts

Init scripts to run Isso as a service (check your distribution’s documentation for your init-system; e.g. Debian uses SysVinit, Fedora uses systemd) if you don’t use FastCGi or uWSGI:

If you’re writing your own init script, you can utilize start-stop-daemon to run Isso in the background (Isso runs in the foreground usually). Below you will find a very basic SysVinit script which you can use for inspiration:

#!/bin/sh
### BEGIN INIT INFO
# Provides:          isso
# Required-Start:    $local_fs $network
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Description:       lightweight Disqus alternative
### END INIT INFO

EXEC=/opt/isso/bin/isso
EXEC_OPTS="-c /etc/isso.cfg run"

RUNAS=isso
PIDFILE=/var/run/isso.pid

start() {
  echo 'Starting service…' >&2
  start-stop-daemon --start --user "$RUNAS" --background --make-pidfile --pidfile $PIDFILE \
                    --exec $EXEC -- $EXEC_OPTS
}

stop() {
  echo 'Stopping service…' >&2
  start-stop-daemon --stop --user "$RUNAS" --pidfile $PIDFILE --exec $EXEC
}

case "$1" in
  start)
    start
    ;;
  stop)
    stop
    ;;
  restart)
    stop
    start
    ;;
  *)
    echo "Usage: $0 {start|stop|restart}"
esac