survey

URL: https://source.atlas.engineer/public/survey


Survey

Survey is a Common Lisp program used to create and collect surveys. It is built on top of the web framework Caveman and uses XML to define the content of surveys.

Installation

Installing a Lisp Implementation

One of the following Lisp implementations is recommended for usage with Survey.

If you are on FreeBSD it is recommended that you build SBCL from the ports collection to get the newest version of SBCL and ASDF.

Installing Quicklisp

The official quicklisp website can provide updated links to downloads, and instructions:

https://www.quicklisp.org

To install quicklisp:

more detailed instructions and other resources are readily available on the quicklisp website.

Run from Source

In a new Terminal execute the following:

  1. lisp to create a new Lisp Repl (replace lisp with sbcl or ccl)
  2. Execute (require :asdf) if asdf is not already loaded
  3. Execute (asdf:load-asd "/full/path/to/survey.asd") to load the Survey system definition (you can not use relative pathnames).
  4. Execute (ql:quickload :survey) to load the survey system into your Lisp image.
  5. Execute (survey:start) to start the Survey server (by default at localhost:5000/.

Initializing the Database

In order to save and create surveys, you will want to initialize the database. To do so, you can make use of the file located at /db/schema.sql, or you can load the Survey system and execute the function (survey.db::initialize-database).

Configuring the Database

Configuration of the database can be done by changing the information in src/config.lisp. You can find out more information in the Caveman2 Documentation.

Running different modes in the Slime REPL

Caveman2, which Survey is built upon uses Envy for configuration management. You are supposed to set the "APPENV" variable to "development" or "production", or nothing at all to control the configuration. The result of these configuration options can be seen in config.lisp.

When executing Survey via Slime, it may not always be possible to have set the environment variable to test different things. In order to do this, you can do something like the following:

Usage

Writing Your Own Surveys

To write your own surveys, you'll need to define them using simple XML. The place you can submit your XML surveys is located at the root page /.

A sample survey XML is provided below:

Upon submission of your form, the program will return a JSON response that looks like the following:

This response indicates the URL of your survey. In the case of the above response, the survey would be located at /survey/7. If you were to visit wwww.example.com/survey/7 (where example.com is your domain), you'll be able to submit responses to your survey.

Collecting Survey Responses

To collect survey responses, you will have to distribute the survey link to your users, in which they will be able to submit responses.

Please Note: There are no cookies or tracking to limit the amount of submissions a user creates.

Collected responses will be stored in the response table of the database. The response table has two columns:

In the table, survey_id corresponds to the ID of your survey, in the above example from Writing Your Own Surveys, the Survey ID would be 7. The data corresponds to the data collected from your survey submission.

An example of a submission could look like the following:

In the above example, false was entered for question 0, and "B" was selected for question 3. The data structure above is known as an alist, you can find more information about it in the Common Lisp Hyperspec entry.

Compilation

Deployment

FreeBSD Deployment

Port SBCL Installation

  1. kill -9 SBCL PID Figure out the PID of SBCL, and Kill it if it is stuck on the aforementioned test.
  2. Manually touch obj/asdf-cache/sb-concurrency/test-passed.test-report
  3. Manually invoke install.sh

Configuring Nginx


#user  nobody;
worker_processes  1;

# This default error log path is compiled-in to make sure configuration parsing
# errors are logged somewhere, especially during unattended boot when stderr
# isn't normally logged anywhere. This path will be touched on every nginx
# start regardless of error log location configured here. See
# https://trac.nginx.org/nginx/ticket/147 for more info.
#
#error_log  /var/log/nginx/error.log;
#

#pid        logs/nginx.pid;


events {
    worker_connections  1024;
}


http {
    include       mime.types;
    default_type  application/octet-stream;

    #log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
    #                  '$status $body_bytes_sent "$http_referer" '
    #                  '"$http_user_agent" "$http_x_forwarded_for"';

    #access_log  logs/access.log  main;

    sendfile        on;
    #tcp_nopush     on;

    #keepalive_timeout  0;
    keepalive_timeout  65;

    #gzip  on;

    server {
        listen       80;
        server_name  www.athena.atlas.engineer athena.atlas.engineer;
        return       301 https://$host$request_uri;
    }

    # HTTPS server
    server {
        listen       443 ssl;
        server_name  athena.atlas.engineer;

        ssl_certificate      /usr/local/etc/letsencrypt/live/athena.atlas.engineer/fullchain.pem;
        ssl_certificate_key  /usr/local/etc/letsencrypt/live/athena.atlas.engineer/privkey.pem;

        ssl_session_cache    shared:SSL:1m;
        ssl_session_timeout  5m;

        ssl_ciphers  HIGH:!aNULL:!MD5;
        ssl_prefer_server_ciphers  on;

        location / {
            proxy_pass   http://127.0.0.1:5000;
        }

    }

}

To use FCGI configuration instead:

location / {
    include /usr/local/etc/nginx/fastcgi_params;
    fastcgi_pass  127.0.0.1:9000;
}

Managing the SSL Certificate

  1. Create a SSL Certificate

    • Stop Nginx service stop nginx
    • sudo certbot certonly --standalone -d athena.atlas.engineer
    • It will tell you where it has dumped the certificates, these are to be used in the Nginx configuration
    • Start Nginx service start nginx
  2. Renew the SSL Certificate

    • make sure to stop Nginx
    • sudo certbot renew --dry-run
    • restart Nginx

Installing Quicklisp

The official quicklisp website can provide updated links to downloads, and instructions:

https://www.quicklisp.org

To install quicklisp:

more detailed instructions and other resources are readily available on the quicklisp website.

Run from Source

In a new Terminal execute the following:

  1. screen to create a new screen.
  2. Navigate to the Survey project directory
  3. Execute service nginx start
  4. Execute make run
  5. Execute C-a d to detach from screen
  6. Close the terminal session

Atlas Engineer

Copyright (c) 2018 Atlas Engineer

License

Licensed under the BSD License.

Contribute:

All contributions and patches are accepted via email. You can use git send-email to create patches and send them to patch@atlas.engineer. To find out more about git email patches please view the official documentation:

https://git-scm.com/docs/git-send-email