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)
-
- 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
- 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
- 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.