SOURCE: Common Lisp Source Hosting Software

SOURCE is software that you can use to host your own remote repositories.

Developer Installation

Installing a Lisp Implementation

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

• Download SBCL: http://sbcl.org/platform-table.html, full installation instructions can be found here: http://sbcl.org/getting.html.

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:

• Download https://beta.quicklisp.org/quicklisp.lisp
• Execute ccl --load quicklisp.lisp to load quicklisp
• Evaluate in the REPL (quicklisp-quickstart:install) to install
• Evaluate in the REPL (ql:add-to-init-file) to add quicklisp to your ccl init file

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

Installation Steps

• Create unix user for hosting git repositories
• Create a config file in the XDG home directory of the user that will be hosting the Git repositories and running this application. The XDG home directory is ~/.config/source/init.lisp. Within your config, you can execute any arbitrary lisp or set any configuration variables.
• Set (in-package :source.config) at the top of the configuration file.

Run from Source

Running different modes in the Slime REPL

Caveman2, which SOURCE is built upon uses Envy for configuration management. You are supposed to set the “APP_ENV” 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 SOURCE 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:

• (setf (osicat:environment-variable "APP_ENV") "development")
• (setf (osicat:environment-variable "APP_ENV") "production")
• …

Interesting Configuration Variables

The list below includes configuration variables you may wish to change, and their defaults.

(defparameter *domain*
  "domain.com")
(defparameter *git-user*
  "git" "User created specifically for this application")
(defparameter *application-root*
  (asdf:system-source-directory :source))
(defparameter *static-directory*
  (merge-pathnames #P"static/" *application-root*))
(defparameter *repository-directory*
  (make-pathname :directory (list :absolute "home" *git-user*)))
(defparameter *git-url-base*
  (concatenate 'string
               "ssh://"
               *git-user*
               "@"
               *domain*
               (uiop:unix-namestring *repository-directory*)))
(defparameter *authorized-keys-path*
  (make-pathname :directory (list :absolute "home" *git-user* ".ssh")
                 :name "authorized_keys"))

How to manually make a repository on a remote server

• Copy SSH keys to ~/.ssh/authorized_keys

Creating a Repository

• su user git
• mkdir -p /home/git/repository.git
• cd /home/git/repository.git
• git init --bare --shared
• Your remote will be ssh://[email protected]/home/git/path.git

Deployment

FreeBSD Deployment

1. pkg install screen
2. pkg install hs-pandoc
3. pkg install sqlite3
4. pkg install nginx
5. pkg install py27-certbot
6. pkg install sbcl-1.4.9,1
7. pkg install fcgi-devkit-2.4.0_5
8. pkg install git
9. adduser git
   • Create user with default settings
10. Create folder public in the git user home directory
11. For all public repositories you will have to enable the Git sample post-update hook.

Port SBCL Installation

• screen
• portsnap fetch; portsnap extract
• C-a d to detach.
• pkg delete -f libiconv to delete the native libiconv implementation for the one specified in the port file dependency
• /usr/ports/lang/sbcl
• make configure
• Enable Threading
• make install
• When compiling SBCL on a small machine with a low amount of RAM, you may encounter a stuck Test: SB-CONCURRENCY-TEST::MAILBOX.SINGLE-PRODUCER-MULTIPLE-CONSUMERS, to fix the problem:

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

Installing Quicklisp

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

https://www.quicklisp.org

To install quicklisp:

• Download https://beta.quicklisp.org/quicklisp.lisp
• Execute lisp --load quicklisp.lisp to load quicklisp (replace lisp with sbcl or ccl)
• Evaluate in the REPL (quicklisp-quickstart:install) to install
• Evaluate in the REPL (ql:add-to-init-file) to add quicklisp to your ccl init file

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

Configuring Nginx

• Edit /etc/rc.conf and add the following line: ~nginx_enable=”YES”~.
• Edit /usr/local/etc/nginx/nginx.conf to use the following configuration:

#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.source.atlas.engineer source.atlas.engineer;
        return       301 https://$host$request_uri;
    }

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

        ssl_certificate      /usr/local/etc/letsencrypt/live/source.atlas.engineer/fullchain.pem;
        ssl_certificate_key  /usr/local/etc/letsencrypt/live/source.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 /public/ {
            alias /usr/home/git/public/;
            autoindex 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;
}

• Start the service service nginx start
• Restart the service service nginx restart

Managing the SSL Certificate

Create a SSL Certificate

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

Renew the SSL Certificate

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

Set-Up Automatic Renewal

• service nginx stop && certbot renew --quiet && service nginx start

Edit the crontab, and run monthly.

• @weekly service nginx stop && certbot renew --quiet && service nginx start

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

Running in Production

• service nginx start
• Execute screen to create a new screen
  • From within the screen navigate to the source repository root
  • Execute make fcgi to run the fcgi server