Deliberatorium Open – Quickstart Guide

Deliberatorum Open is an open-source release of the Deliberatorium, a web-based collective-intelligence platform developed by Mark Klein at the Massachusetts Institute of Technology. It incorporates a subset of the Deliberatorium’s full functionality. Deliberatorium Open is developed in Common LISP, a LISP dialect, with the Clozure CL implementation

Community Open Edition (OS X)

MINIMUM REQUIREMENTS

• OS X 10.6+
• fixed IPv4
• 2GB RAM (4GB recommended)
• 10GB HDD

INSTALL CCL

1. get a Macintosh computer with a fixed IP address to act as a server. A Mac VPS with at least 2GB RAM is required. At least 4GB RAM are recommended.
2. get Clozure Common Lisp (CCL)
3. 1. download Clozure CL from Mac App Store RECOMMENDED // you will need an AppleID

or

2.2. download the Mac version from the official github repository

N.B.: other OS are supported. Please refer to the official Clozure website for further information and installation procedures

INSTALL DELIBERATORIUM – BASIC CONFIGURATION

3. download the Deliberatorium Open Source code from Deliberatorium Open Source
4. unzip the code in your Documents directory. You will obtain a directory named “open” with everything you need to startup your eliberatorium Open Source instance.

N.B.: The default location of the system will be into Documents directory. If you want to change the location of your Deliberatorium Open source instance within your folder tree, and/or the name of the “Deliberatorium” directory, please remember to change accordingly the following paths into the “startup.lisp” file:

    (defglobal *root-directory* "/Users/markklein/documents/projects/deliberatorium/open/") ; directory where deliberatorium code resides

by replacing the path markklein/documents/projects/deliberatorium/open/ with your desired path.

5. edit the following MANDATORY variables in the file “startup.lisp” in the Deliberatorium Open folder named “Deliberatorium”:

           (defglobal *deliberatorium-host* "http://localhost:8000/") ; the root URL of the machine that is running the deliberatorium server

6. edit the following NON-MANDATORY in the file “startup.lisp” in the Deliberatorium Open folder named “Deliberatorium”:

           (defglobal *system-email* "...") ; the email address that the Deliberatorium sends email from
   (defglobal *outgoing-mail-host* "...") ; email server that the Deliberatorium uses to send email out
   (defglobal *backup-period* 1800) ; time between backups, in seconds
   (defglobal *backups-saved* 200) ; number of backups saved

7. launch CCL:
8. 1 double click on the installed icon inside your Application folder
9. Menu “File” > “Load File” > “startup.lisp” // load the edited “startup.lisp” file
10. If everything’s fine, you’re ready to go! The system will be available at http://YOUR DOMAIN OR FIXED IP ADDRESS:8000/ci/
11. The sysadmin account starts has login/password: sysadmin/password

PORT FORWARDING & SECURITY

INSTALL NGNIX WEBSERVER

In order to install ngnix webserver for enabling port fowarding, the easiest way is to install the brew packet manager, following Homebrew official website instructions

• open a Terminal and paste the following command, then press the “RETURN” key

          $ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

• if permissions errors shows up, please take a look at your admin user permissions. If they do not fit, execute the following command

          $ sudo chown -R $(whoami):admin /usr/local && sudo chmod -R g+rwx /usr/local

• install ngnix with brew

          $ brew install nginx

• edit ngnix config file by changing “listen” (port) and “server_name” variables as following (replace “vi” with your preferred text editor):

          $ sudo vi /usr/local/etc/nginx/nginx.conf
  
      server {
          listen       80;
          server_name  YOUR DOMAIN OR FIXED IP ADDRESS;

• NOT MANDATORY / add IPV6 support
• add the following lines after the previous one you have modified for “listen” and “server_name” variables

              listen [::]:80; # for IPV6

• start ngnix

          $ sudo brew services start nginx

• test nginx

in order to test if ngnix is correctly working, open a web browser and go to YOUR DOMAIN OR FIXED IP ADDRESS; if everything’s fine, the ngnix welcome page will show up

CREATE HTTPS CERTIFICATES

There are different ways to obtain HTTPS certificates. If you prefer not to rely on payed 3d-party validation authorities, you can use certbot from EFF (Electronic Frontier Foundation), and Let’s Encrypt free validation authority. You will create self-signed valid HTTPS certificates.

N.B.: You will need a domain name – you cannot create valid HTTPS certificates for an IP address

• download certbot from EFF website by chosing the right version for your webserver. In our case, it will be ngnix and OSX

certbot for ngnix/OSX

• install certbot with brew // it will install also python, PIP and other required packages

          $ brew install certbot
  $ sudo certbot --nginx

• follow the instructions. You’ll have to

1. type your sudo user password
2. Enter email address (used for urgent renewal and security notices)
3. type ‘A’ for Agree with the license notes
4. decide by typing N or Y if you want to receive EFF communications
5. answer by typing the number of the wanted domain (Which names would you like to activate HTTPS for?)
6. chose if you want no redirection [1] or redirection [2] // we strongly suggest to choose the [2] option.

• if everything’s fine, you’ll be prompted to a

“Congratulations! You have successfully enabled YOUR DOMAIN

with also a test address

PORT FORWARDING CONFIGURATION

• edit ngnix config file

          $ sudo vi  /usr/local/etc/nginx/nginx.conf

• comment out these two lines in the “location” section. Default “location” section looks like:

          location / {
      # root   html;
      # index  index.html index.htm;
              }

• then add this line after the “index” line

              proxy_pass http://YOUR DOMAIN:8000;

• the modified “location” section looks like:

          location / {
          root   html;
          index  index.html index.htm;
          proxy_pass http://YOUR DOMAIN:8000;
           }

N.B.: PLEASE MAKE SURE YOU TYPE THE ADDRESS WITH HTTP – NOT HTTPS!

• restart nginx to be sure every modification will take effect

          $ sudo brew services restart nginx 

• test nginx port forwarding & HTTPS

open a web browser and go to YOUR DOMAIN; if everything’s fine, now a hutchentoot page will show up, with “Not Found The requested URL / was not found on this server.”. Please note the green lock on the left of the address: your connection is secure.

• your server is up and running athttps://YOUR DOMAIN/ci/

SETUP SSL CERTIFICATES

Let’s encrypt auto-generates the pem files in the following path of yout server:

/etc/letsencrypt/live/YOUR DOMAIN/

you can find them with a simple find / -name “fullchain.pem” or with your preferred UI finder

the folder /etc/letsencrypt/live/YOUR DOMAIN/ contains:

-cert.pem
-fullchain.pem
-privkey.pem
-chain.pem

do not move these files. nginx will serve them to hunchentoot automatically, by changing the following declaration in the startup.lisp file

(defglobal *deliberatorium-host* "http://localhost:8000/") ; 

This declaration will captures whether port-forwarding and SSL are enabled or not. If only portforwarding is enabled, for example, you have to delete the port and the declaration will look like

(defglobal *deliberatorium-host* "http://localhost/") ;

in order to enable your domain name, you will need to change “localhost” with your domain name, and the declaration will look like

(defglobal *deliberatorium-host* "http://YOUR DOMAIN NAME/") ;

in order to enable SSL over HTTP, you will need to change “http” to “https” and the declaration will look like

(defglobal *deliberatorium-host* "https://YOUR DOMAIN/") ; 

please note that web address protocol changed from http into https. In order to test https:

• restart Clozure CL and reload startup.lisp

DELIBERATORIUM OPTIONAL ROOT REDIRECTION

In order to obtain a cleaner URL for your Deliberatorium system, you can optionally redirect the path by editing the ngnix configuration file

• edit ngnix config file

          $ sudo vi /usr/local/etc/nginx/nginx.conf

• in the “location” section, modify the line starting with “proxy_pass” by adding the “/ci/” path. This directive will re-write URLs. It is very important to write “/ci/” between two “/”.
• the modified “location” section looks like:

          location / {
              root   html;
              index  index.html index.htm;
                  proxy_pass http://YOUR DOMAIN:8000/ci/;
              }

• Now you are able to connect to your Deliberatorium instance by typing on a web browser

          http://YOUR DOMAIN

License Notes

This code is being released under AGPLv3. Please adhere with this license. You can find a full copy of the license in the “LICENSE.txt”.

N.B.: This code release includes a major package that Dr. Klein did not develop:

• hunchentoot web server, available at https://edicl.github.io/hunchentoot/

plus several F/LOSS packages and libraries

Please read the licensing information for those packages to make sure you are in compliance.