@@ 0,0 1,119 @@
+# 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.
+
+## Development
+
+### Prepare the database
+
+Feather uses PostgreSQL.
+
+0. Create a role `feather_dev` with password `feather_dev`.
+0. 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.
+
+### 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
+```
+
+