Common Lisp web application template.
Install the assets directory.
Fix application name in systemd script.
Fix source of systemd script.

heads

tip
browse log

clone

read-only
https://hg.sr.ht/~wnortje/feather
read/write
ssh://hg@hg.sr.ht/~wnortje/feather

Feather Web Application Template

Feather is a template for web application development. It is intended to give a new web application a jump start by making a lot of the basic decisions needed at the start of a project without forcing you to commit to those choices like web frameworks often do.

The easiest way to use it is to clone this project and start modifying the code to be your application. The template is a functioning "Hello world" application complete with database access, migrations and tests.

Buy the book

I wrote a book on how to deploy Common Lisp web applications to a cloud based server. The step-by-step guide in the book uses this template to demonstrate how to set up a CL web application. More detail at: Deploying Common Lisp web applications

Clone the repo

Please note: this is a Mercurial repo. To clone use the hg command.

hg clone https://hg.sr.ht/~wnortje/feather

Development

Prepare the database

Feather uses PostgreSQL.

  1. Create a role feather_dev with password feather_dev.
  2. Create a database feather_dev owned by role feather_dev.

Or change the values in specials.lisp.

Set up Quicklisp and ASDF

(load "PATH-TO-REPO/src/prep-quicklisp.lisp")

Run migrations

(ql:quickload :feather/migrate)

Clear old migrations

(setf database-migrations::*migrations* nil)

Reload all migrations

(ASDF/OPERATE:LOAD-SYSTEM "feather/migrate" :VERBOSE t :force t)

Upgrade

(feather-migrate:upgrade)

Downgrade

(feather-migrate:downgrade NUM-TO-DOWNGRADE)

Run the web server

(ql:quickload :feather)
(feather:start :debug-logs-p t :user-dribble-p t)
(feather:stop)

Run tests

(ql:quickload :feather/test)
(5am:run! `feather-test::main)
(5am:run-all-tests)

Architecture

The code architecture is a 3 layered approach. Each layer only interacts with the layers above and below it.

(3) UI
    |
(2) Logic
    |
(1) Data model
  1. Data model : The data model provides the interface to the data. It is mostly DB access but it can also be any other form of data store.

  2. Logic : The logic layer implements the application logic. Most of the work happens here.

  3. UI : The UI layer interacts the user.

Production

Preparation

  • Install OS packages: build-essential, m4, mercurial, postgres, postgres-contrib

  • Prepare the production database similar to the one for development.

  • Install CCL or SBCL in your path.

  • Install Quicklisp.

  • Install buildapp in your path.

  • There are configuration files for Nginx and Systemd in the config directory of the repo.

  • Clone the modified feather repo on the server.

  • Create a directory config next to the cloned repo directory.

  • Inside config create a file cfg-feather.lisp with the following format:

    (
      :db-user "prod-user"
      :db-name "prod-db-name"
      :db-pwd "prod-pwd"
      :db-host "prod-host"
    )
    

Deploy

The following commands are executed inside the cloned repo directory.

hg checkout default
hg pull -u
make clean all
make migrate
sudo make install
sudo systemctl restart feather