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

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.
get Clozure Common Lisp (CCL)
1. download Clozure CL from Mac App Store RECOMMENDED // you will need an AppleID

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

download the Deliberatorium Open Source code from Deliberatorium Open Source
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.

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

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

launch CCL:
1 double click on the installed icon inside your Application folder
Menu “File” > “Load File” > “startup.lisp” // load the edited “startup.lisp” file
If everything’s fine, you’re ready to go! The system will be available at http://YOUR DOMAIN OR FIXED IP ADDRESS:8000/ci/
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

type your sudo user password
Enter email address (used for urgent renewal and security notices)
type ‘A’ for Agree with the license notes
decide by typing N or Y if you want to receive EFF communications
answer by typing the number of the wanted domain (Which names would you like to activate HTTPS for?)
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.

weDialogue

Deliberatorium Open Source – Guide