alt text Isso Comments with Lighttpd

Isso is a lightweight open-source commenting server you can set up and run yourself that provides a user comment interface similar to third party services offered by companies like Disqus. Isso is simple to administrate, maintains identity, allows anonymous comments with basic spam guard protection and has email notification support. It uses JavaScript and cross-origin resource sharing for easy integration into (static) websites.

Isso Deployment Overview

Keeping in line with the previous article listed on the left, this Howto is written as a further addition for the same Ubuntu Linux Mint installation running the Lighttpd webserver. It details how to add user comments to your site posts (a.k.a. blog).

The Isso comment server system is written in Python and has a default installation using the gevent networking library. The gevent system is their default due to its ease of installation, however it is only meant as a low traffic solution and is normally implemented through an Nginx HTTP reverse proxy server. The default installation instructions also call for the install of Python in a non-Distro specific method.

Ubuntu Linux has a package management system called Apt for installing, upgrading, configuring, and removing software. Whenever possible it is recommended to use Apt for adding software to ensure your OS, and the list of all its packages, stays intact.

Installation and Configuration

This installation manages to use Ubuntu default Apt packages along with just a few configuration files, created manually, in a single folder.

  1. Install the base packages. Open up a terminal window to use the command prompt and paste the following
    sudo apt-get install isso sqlite3 uwsgi uwsgi-plugin-python uwsgi-plugin-sqlite3
    
  2. The uWSGI implementation of Isso needs a spool directory. Since uwsgi will be run as user isso let isso own the folder.
    sudo mkdir /var/spool/uwsgi
    sudo mkdir /var/spool/uwsgi/isso1
    sudo chown -R isso:isso /var/spool/uwsgi
    
  3. The Ubuntu isso package creates a user named isso with a home dir of /var/lib/isso. All isso configuration used in this setup will be placed here and be organized in roughly the same folder structure style Ubuntu uses.
    Create an ini file in /var/lib/isso/etc for uWSGI so it can launch Isso as isso and provide FastCGI translation for the lighttpd web server.
    sudo mkdir /var/lib/isso/etc
    sudo nano /var/lib/isso/etc/isso1.ini
    

    Paste the following contents:

    [uwsgi]
    uid = isso
    plugin = python
    strict = true
    fastcgi-socket = :8081
    master = true
    processes = 1
    threads = 2
    cache2 = name=hash,items=1024,blocksize=32
    spooler = /var/spool/uwsgi/isso1
    module = isso.run
    chdir = /var/lib/isso
    #virtualenv = /var/lib/isso
    env = ISSO_SETTINGS=/var/lib/isso/etc/isso1.cfg
    die-on-term = true
    
  4. Create a configuration file for isso1 settings.
    sudo nano /var/lib/isso/etc/isso1.cfg
    

    Paste the following:
    Modify the web address to your site address as well as your SMTP mail settings.

    ;_GENERAL_SECTION_
    [general]
    ;database location. automatically created if doesnt already exist
    dbpath = /var/lib/isso/isso1.db
    ;this is the name in your header [i.e. <script data-isso='/isso1']
    name = isso1
    ;your website or blog where isso1 comment input form is desired
    host =
     http://yoursiteaddress.net/
     https://yoursiteaddress.net/
    ;logfile.
    log-file = /var/log/isso/isso.log
    ;get notifications by email
    notify = smtp
    ;_SERVER_SECTION_
    [server]
    ;port to listen on... needs to match uwsgi ini and fastcgi in lighttpd conf 
    listen = http://localhost:8081/
    ;_SMTP_SECTION_ [for notifications]
    [smtp]
    ;these are the details for the 'from' address Isso uses to send notifications
    ;you might want to use a dedicated email account for this
    username = your.username@yourispprovider.net
    password = your5ecr3tpassword!
    host = mail.ispprovider.net
    port = 587
    security = starttls
    ;this is the 'to' address Isso sends notification emails to
    to = yourletmeknowtheresacomment.address@themailservice.net
    ;from address as shown on emails. should correspond to sender account above
    from = "isso comments" <your.username@yourispprovider.net>
    timeout = 10
    ;_GUARD_SECTION_ - Issos basic spam protection
    [guard]
    enabled = true
    ;no. of allowed comments per minute
    ratelimit = 2
    ;no of direct replies allowed
    direct-reply = 3
    ;can people reply to their own comments while edit window still open
    reply-to-self = false
    ;do commenters need to leave a name
    require-author = true
    ;do commenters need to provide an email
    require-email = false
    ;_MARKUP_SECTION_ allowed markdown in comments. [uses misaka markdown]
    [markup]
    ;default options allow most 'unharmful' markdown
    options = strikethrough, superscript, autolink
    ;default allowed = a, blockquote, br, code, del, em, h1, h2, h3, h4, h5, h6, hr, ins, li, ol, p, pre, strong, table, tbody, td, th, thead, ul
    ;allowed-elements =
    ;default allowed = align, href
    ;allowed-attributes
    ;_IDENTICON_SECTION_
    ;creates identicons for users across isso installations
    [hash]
    ;OK to use this salt
    salt = Eech7co8Ohloopo9Ol6baimi
    algorithm = pbkdf2
    ;_MODERATION_SECTION_ comments must be moderated before publication
    ;NOTE: requires notify=smtp to be set in the [general] section
    [moderation]
    enabled=true
    

    Make isso1 a service

  5. Isso1 will need to be started as a service. In order to achieve this create a BASH launcher in /var/lib/isso/sbin.
    sudo nano /var/lib/isso/sbin/isso1
    

    Paste the following:

    #!/bin/bash
    # use uwsgi to launch isso1 with fastcgi support 
    /usr/bin/uwsgi --ini /var/lib/isso/etc/isso1.ini
    
  6. Make sure all the configuration folders and files are properly owned Recursively by isso and the BASH launcher is executable by isso.
    sudo chown -R isso:isso /var/lib/isso
    sudo chmod u+x /var/lib/isso/sbin/isso1
    
  7. Attach isso1 as an available service by utilizing SystemD. Create a .service file in /etc/systemd/system and state the service is to run as user isso.
    sudo nano /etc/systemd/system/isso1.service
    

    Paste the following:

    [Unit]
    Description=Isso1 service
    [Service]
    User=isso
    WorkingDirectory=/var/lib/isso
    ExecStart=/var/lib/isso/sbin/isso1
    SuccessExitStatus=143
    TimeoutStopSec=10
    Restart=on-failure
    RestartSec=5
    [Install]
    WantedBy=multi-user.target
    

    Add isso1 to Lighttpd

  8. Open the lighttpd config file and add mod_fastcgi to your list of server modules. Pay close attention to make sure all rows except the last have commas.
    server.modules                 = (
                                  "mod_access",
                                  "mod_accesslog",
                                  "mod_alias",
                                  "mod_compress",
                                  "mod_auth",
                                  "mod_evhost",
                                  "mod_rewrite",
                                  "mod_redirect",
                                  "mod_fastcgi"
    )
    

    Further down, add isso1 to your fastcgi section (used often for php), pay close attention to the commas. If you dont have a fastcgi section, create it (without the php part).

    fastcgi.server = (
     ".php" => (
         "localhost" => (
             "bin-path"  => "/usr/bin/php-cgi",
             "host" => "127.0.0.1",
             "port" => 9000
         )
     ),
     "/isso1" => (
          "uwsgi" => (
          "host" => "127.0.0.1",
          "port" => 8081,
          "check-local" => "disable",
          "max-procs" => 1
         )
     )
    )
    

    Save and restart Lighttpd

    sudo service lighttpd restart
    

    Test the isso1 Install

  9. Start the isso1 service. When starting it will create the sqlite3 database file /var/lib/isso/isso1.db if it doesn’t exist. With SystemD you can connect your console to the current output with the status command.
    sudo systemctl start isso1
    sudo systemctl status isso1
    

    If all went well you should see some output similar to this:

     Main PID: 31597 (isso1)
    CGroup: /system.slice/isso1.service
            ├─31597 /bin/bash /var/lib/isso/sbin/isso1
            ├─31600 /usr/bin/uwsgi --ini /var/lib/isso/etc/isso1.ini
    

    Connect isso1 to Your Site

  10. To connect the Isso service to your website you technically only need to manually add something like the following data-isso code to the bottom of the body section of your page and an isso-thread section, shown further down, added to the page where you want the comment form to appear.
    Jekyll themes however are often set up with some form of comments provider support. The following will use the Minimal Mistakes theme as its example.
    Minimal Mistakes is set up quite nicely for comments providers, but has no specific section for isso. It does have a custom option which will do nicely.
    1. Edit your main _config.yml file and add/set the comments provider option.
      comments:
        provider               : "custom" # false (default), "disqus", "discourse", "facebook", "google-plus", "staticman", "custom"
      
    2. Create a _includes/comments-providers/custom.html in your jekyll project.
      nano _includes/comments-providers/custom.html
      

      Paste the following:
      Alter the website address accordingly.

        <script data-isso="http://yoursiteaddress.net/isso1"
      data-isso-id="thread-id"
      data-isso-css="true"
      data-isso-lang="en"
      data-isso-reply-to-self="false"
      data-isso-require-author="false"
      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-avatar-fg="#9abf88 #5698c4 #e279a3 #9163b6 ..."
      data-isso-vote="true"
      data-isso-vote-levels=""
      data-isso-feed="false"
      src="http://yoursiteaddress.net/isso/js/embed.min.js">
        </script>
      
    3. Check your Jekyll project folder for _layouts/single.html. If you have yet to alter the _layouts/single.html and dont have it simply make a copy of the original one from the theme folder into the _layouts folder of your project. Any file in your project overrides the original of the theme. You can easily find the themes folder location by issuing:
      cd `bundle show minimal-mistakes`
      

      Edit your copy of _layouts/single.html and add the following to the comments section.

      <h2 class="panel">Comments</h2>
              <section id="isso-thread"></section>
      </section>
      
    4. When you want to enable comments in a post just add comments: true to the top of each post.md file. If at a later date you want to close comments on that post simply set it to false and rebuild.

      ATTENTION: embed.js

  11. Isso was developed to internally contain its embed.js file and serve it on-the-fly. Unfortunately at the time of this howto the version of Isso used in the Ubuntu package serves up a corrupt embed.js file. A work-around is to place a good compatible version directly on your site. A copy of the file can be downloaded here if you need it (right-click, save link as). Place it in an isso/js/ folder at the root of your site.

    Add isso1 to Bootup

  12. Make isso start at boot time
    sudo systemctl enable isso1
    

    Multi-Website Config (optional)

  13. This installation can easily be configured for a system serving multiple websites. If you require an Isso comment instance per site create the extra spool folders you need.
    sudo mkdir /var/spool/uwsgi/isso2
    sudo chown -R isso:isso /var/spool/uwsgi
    
  14. Create your etc/isso2.cfg, etc/isso2.ini, BASH launcher sbin/isso2 and isso2.service files using the same instructions in steps 3 - 7, but altering the pasted data to reference the next number (i.e. any instance of isso1 to be replaced with isso2 - example isso2.db, etc.), corresponding website (i.e. http://yourotherwebsite.net, etc.) and next port number (i.e. instead of 8081 use 8082 - example http://localhost:8082.).
    As an example step 3 would look like:
    sudo nano /var/lib/isso/etc/isso2.ini
    

    Paste the following contents:

    [uwsgi]
    uid = isso
    plugin = python
    strict = true
    fastcgi-socket = :8082
    master = true
    processes = 1
    threads = 2
    cache2 = name=hash,items=1024,blocksize=32
    spooler = /var/spool/uwsgi/isso2
    module = isso.run
    chdir = /var/lib/isso
    #virtualenv = /var/lib/isso
    env = ISSO_SETTINGS=/var/lib/isso/etc/isso2.cfg
    die-on-term = true
    
  15. After repeating step 3 - 7 as mentioned above add another entry in the lighttpd config file for isso2 fastcgi. Having two isso entries and no php would look like the following:
    fastcgi.server = (
    "/isso1" => (
         "uwsgi" => (
         "host" => "127.0.0.1",
         "port" => 8081,
         "check-local" => "disable",
         "max-procs" => 1
        )
    ),
    "/isso2" => (
         "uwsgi" => (
         "host" => "127.0.0.1",
         "port" => 8082,
         "check-local" => "disable",
         "max-procs" => 1
        )
    )
    )
    

    Save and restart Lighttpd

    sudo service lighttpd restart
    

    Start the isso2 service and add it to the bootup.

    sudo systemctl start isso2
    sudo systemctl enable isso2
    
  16. For connecting isso2 to your other site you would alter step 10. 2. to use data-isso=”http://yourotherwebsite.net/isso2” and src=”http://yourotherwebsite.net/isso/js/embed.min.js”