# Blogging with Coleslaw

posted on 2013-10-14 10:34:44

Coleslaw is one of many static site generators and creates static HTML pages. It uses Common Lisp in the backend. In my case markdown is used as the post format. This post will cover issues I encountered during install and initial usage. My Server is running a headless CentOS 6 install.

As of October 2013 the SBCL version in the yum repo's is 1.0.38. When trying to run coleslaw a error occurs due to the cl-fad lib. Installing it via Quicklisp fails. As of SBCL 1.0.44 the missing functionality seems to be included: enhancement: new function: SB-EXT:DELETE-DIRECTORY is now provided.

I recall all this from memory. So I am not completely sure this was the line in question. Since latest version at the moment is 1.1.12, this does not matter much. Except for others encountering similar errors and finding this via google. :)

How to install the newest SBCL version and getting Quicklisp up and running, is already covered here.

Now first a description how my coleslaw setup works and what technologies are used, in case troubleshooting is needed later on. The blog runs on a hosted vserver, stored in a git repository served by gitolite (eventually gitlab will be put to use). Once changes are pushed into the git repo, via a post-receive hook the lisp code for converting the markdown posts is triggered. The .html files are copied to another folder which is served over an apache web server.

Posts have have the following structure, this is taken from this one here:

;;;;;
title: Blogging with Coleslaw
tags: coleslaw,sbcl,common lisp,lisp
date: 2013-10-14 10:34:44
format: md
;;;;;
Coleslaw is one of [many static site generators] (http://staticsitegenerators.net/) and creates ...


For convenience reasons posts have filenames like: 003-installing.coleslaw.post

Indicating content and having a prepended number for easier editing. The .post extension is needed. Posts are the only files that reside in the blogging repository that is checked out onto my client workstation. All conversion code is loaded via Quicklisp, no need to set anything up besides what will be covered here. To phrase it differently, in your blog repository NO additional directory structure is needed for post organization, NO additional code is needed. Things just work. I.e. this is what resides in my cloned repo called blog currently:

[sjas@lorelei ~/work/blog]% ls
_test.post.sample
001-first.post.post
002-installing.sbcl.post
003-installing.coleslaw.post


It will not be disclosed how long just this took me to find out about the non-existant directory structure. :)

On the server the repository is stored as a bare repo, nothing to take care of since gitolite will handle this by itself. Only thing to fix is the post-receive hook. Hooks in git enable bash actions to be triggered upon repository interactions. bash code to happen prior or after pushes, commits, etc. is defined in hook files. These are placed in the .git folder of the repository where they should act. Here this means, the post-receive file has to be put into /var/lib/gitolite/repositories/blog.git/hooks on the server. If it were put within the client-side repo it will not work.

In my case this is the content of the file called post-receive:

########## CONFIGURATION VALUES ##########

# TMP_GIT_CLONE _must_ match one of the following in coleslawrc:
#   * The :repo argument (for a single-site setup) _or_
#   * An alist key (for a multi-site setup)
TMP_GIT_CLONE=/var/lib/gitolite/repositories/blog.git/tmp/

# Set LISP to your preferred implementation. The following
# implementations are currently supported:
#   * sbcl
#   * ccl
LISP=sbcl

########## DON'T EDIT ANYTHING BELOW THIS LINE ##########

if cd dirname "$0"/..; then GIT_REPO=pwd cd$OLDPWD || exit 1
else
exit 1
fi

git clone $GIT_REPO$TMP_GIT_CLONE || exit 1

if [ $LISP = sbcl ]; then sbcl --eval "(ql:quickload 'coleslaw)" \ --eval "(coleslaw:main \"$TMP_GIT_CLONE\")" \
--eval "(coleslaw::exit)"
elif [ $LISP = ccl ]; then echo "(ql:quickload 'coleslaw)(coleslaw:main \"$TMP_GIT_CLONE\")(coleslaw::exit)" | ccl -b
else
exit 1
fi

rm -rf \$TMP_GIT_CLONE
exit


TMP_GIT_CLONE must point to a temporal folder which is not used otherwise. This is not the folder where your repository resides, or where the html code will be pushed to. It is needed for generation purposes and will be deleted immediatly after posting.

Further on the server the .coleslawrc has to be placed in the home folder of the user being responsible for gitolite.

My .coleslawrc in /var/lib/gitolite on the server:

(:author "sjas"
:deploy-dir "/var/www/html/sjas/blog/" ;; folder to be served
:domain "http://blog.sjas.de"
:feeds ("lisp")
:plugins ((mathjax) (sitemap))
:repo "/var/lib/gitolite/repositories/blog.git/tmp/" ;; tempfolder before stuff gets moved into DEPLOY, same as in post-receive
:sitenav ((:url "http://blog.sjas.de/" :name "Home")
(:url "http://github.com/sjas" :name "Code"))
:staging-dir "/tmp/coleslaw/"
:title "A year and a smile."
:theme "hyde")


Once all this is set, a virtual host entry in the apache config has to be created, maybe like this one here:

<VirtualHost blog.sjas.de:80>

ServerName blog.sjas.de

DocumentRoot /var/www/html/sjas/blog/.curr/

<Directory />
Order allow,deny
allow from all
</Directory>

ErrorLog /var/log/blogsjas/error_log
CustomLog /var/log/blogsjas/access common

<IfModule mpm_itk_module>
AssignUserId git git
</IfModule>

</VirtualHost>


Trick here is to set the DocumentRoot pointing to the symlink .curr which is created by coleslaw.

The mpm_itk_module is an apache extension to let a vhost run under a different user. Since I have the blog und git running under the same user, I do not have to watch out for file permission errors. Last thing to note here is, I forgot to create the ErrorLog and CustomLog files. Because of that nothing was served except the apache standard page, beside all else being set up properly. Once this was fixed, things looked like this on my workstation:

[sjas@lorelei ~/work/blog]% git add -A && git commit -m "update coleslaw" && git push
[master c9a5] update coleslaw
3 files changed, 11 insertions(+), 2 deletions(-)
delete mode 100644 .003-installing.coleslaw.post.swp
create mode 100644 .gitignore
Counting objects: 6, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (4/4), 688 bytes, done.
Total 4 (delta 2), reused 0 (delta 0)
remote: Initialized empty Git repository in /var/lib/gitolite/repositories/blog.git/tmp/.git/
remote: This is SBCL 1.1.12.14-b2ed34b, an implementation of ANSI Common Lisp.
remote:
remote: SBCL is free software, provided as is, with absolutely no warranty.
remote: It is mostly in the public domain; some portions are provided under
remote: BSD-style licenses.  See the CREDITS and COPYING files in the
remote:     coleslaw
remote: .......................
remote: ; compiling file "/var/lib/gitolite/quicklisp/dists/quicklisp/software/coleslaw-20131003-git/plugins/mathjax.lisp" (written 12 OCT 2013 12:59:42 AM):
remote: ; compiling (DEFPACKAGE :COLESLAW-MATHJAX ...)
remote: ; compiling (IN-PACKAGE :COLESLAW-MATHJAX)
remote: ; compiling (DEFVAR *MATHJAX-HEADER* ...)
remote: ; compiling (DEFUN ENABLE ...)
remote:
remote: ; /var/lib/gitolite/quicklisp/dists/quicklisp/software/coleslaw-20131003-git/plugins/mathjax.fasl written
remote: ; compilation finished in 0:00:00.016
remote: ; compiling file "/var/lib/gitolite/quicklisp/dists/quicklisp/software/coleslaw-20131003-git/plugins/sitemap.lisp" (written 12 OCT 2013 12:59:42 AM):
remote: ; compiling (DEFPACKAGE :COLESLAW-SITEMAP ...)
remote: ; compiling (IN-PACKAGE :COLESLAW-SITEMAP)
remote: ; compiling (DEFMETHOD DEPLOY ...)
remote: ; compiling (DEFUN ENABLE ...)
remote:
remote: ; /var/lib/gitolite/quicklisp/dists/quicklisp/software/coleslaw-20131003-git/plugins/sitemap.fasl written
remote: ; compilation finished in 0:00:00.006
remote: ; cp -R /var/lib/gitolite/quicklisp/dists/quicklisp/software/coleslaw-20131003-git/themes/hyde/css .
remote: ; ln -sfn 1.html index.html
remote: ; mv /tmp/coleslaw/ /var/www/html/sjas/blog/generated/3590675951
remote: ; rm -r /var/www/html/sjas/blog/generated/3590675441/
remote: ; ln -sfn /var/www/html/sjas/blog/.curr /var/www/html/sjas/blog/.prev
remote: ; ln -sfn /var/www/html/sjas/blog/generated/3590675951 /var/www/html/sjas/blog/.curr
To git@sjas.de:blog
e895..c9a5  master -> master
[sjas@lorelei ~/work/blog]%


And the then the software was up and running and the result is what you see here.

All this seems like an awful lot of work, but I wanted a fast, clean-looking, self-hosted blogging solution, working with git and being LISP-based for learning purposes. Other options would have been the clojure-based ones listed here and here.

This grew longer than anticipated, questions please via twitter until I get DISQUS up in here.

# Hello World

posted on 2013-10-12 15:18:00

This is the first posting using a new static site generator based on Common Lisp. Setting this up could have been way easier with better documentation.

Next post will cover problems I encountered. For now back to real work.

P.S.
This markdown cheat sheet might help me writing posts.

Unless otherwise credited all material by sjas