, _ / _, _ / _/ _, / ) _ _, (__ (/ //) () (/ (/ (__ //)_) developer friendly :: type safe :: performant
LambdaCms is a set of packaged libraries —containing subsites for the Yesod application framework— which allow rapid development of robust and highly performant websites with content management functionality.
lambdacms-* packages each provide some functionality and can depend
on eachother by specifying them as dependencies in their
The only mandatory package is
lambdacms-core, it provides
functionality that all other
lambdacms-* packages depend on.
As mentioned, each
lambdacms-* package contains a subsite which is
"mounted" in a standard Yesod application we call the "base application",
or simply "base".
To mount a packaged subsite specify it as a dependency to the base app's
.cabal file and add some glue code as explained below.
In the base app we have to:
- configure a database connection,
- organize the admin backend's menu,
- specify the authentication strategies for admins, and
- define admin user roles and their permissions.
In the base app we optionally may also:
- override default behavior,
- override UI texts,
- provide a means to send email notifications, and last but not least,
- write the themes so the website can actually be visited (recommended).
2. Setting up a site with LambdaCms
This section describes the steps of setting up a site with LambdaCms.
For the purpose of integration testing we also provide a script that covers the steps below. We recommend following the steps below as it provides more guidance and helps to understand the inner workings.
NOTE: We're currently in the process using
stack, and upgrading to
GHC 7.10. This means we will use Stackage's
set until LTS 3 is released.
You need to be reasonably acquinted with Haskell in order to follow along with this guide. To learn basic Haskell skills we recommend Brent Yorgey's excellent Introduction to Haskell course.
Besides Haskell you need to be somewhat familliar with:
- the web technologies (HTTP, HTML, CSS, JS, REST),
- RDBMS/SQL (LambdaCms makes use of a relational database), and
- the Yesod web application framework (for which an awesome book exists).
For the connection with the database, Haskell libraries typically compile against non-Haskell libraries. One of the following libraries needs to be available:
- Homebrew (OSX):
- Homebrew (OSX):
For Sqlite (required for building the test suite)
- Homebrew (OSX):
On other platforms these packages might have different names, but are most likely available.
If you are going to use a database other than Sqlite (which directly writes to a file), you need to have a database accessible from where you run your site. This means you might have to install and setup a database server locally.
Create a project folder
Choose a name for your project. In below we choose
mysite, which you
probably want to change. Make sure to choose a valid unix file name
to avoid naming issues. Now create a directory for your project and
cd into it, by running the following commands:
export PROJECT_NAME=mysite; mkdir $PROJECT_NAME; cd $PROJECT_NAME
Initializing the base application
First we need to install the
yesod command, this command requires a
lot of dependent packages to be downloaded and build (may a while).
stack install yesod-bin --resolver nightly-2015-07-24
With the following command you create a "scaffolded" Yesod application. The command is interactive; you need to supply some configuration values. Pick the database of your choice, and choose a project name:
yesod init -n $PROJECT_NAME --bare
If you have chosen a database other than Sqlite, you need to create a
database and a sufficiently priviledged database user, and set these
credentials in the
Now we will create a
stack.yaml file for this project which specifies
the nightly snapshot we would like to use.
stack init --resolver nightly-2015-07-24
NOTE: This command complains that the some version constraints in
$PROJECT_NAME.cabal file are too strict. Please raise the
upper bounds of these dependencies manually. This step may be
removed once LTS 3 is out.
This installs all dependencies and builds the scaffoled application (may take a while):
When you experience problems during builds, while using LTS
we consider this a bug. Please
raise an issue.
Testing the scaffoled Yesod app
The following commands will run your scaffolded Yesod application in development mode.
stack exec yesod devel
Now fire some requests at it by pointing your browser to:
If all went well you are now ready to add LambdaCms to your app.
Patching a freshly init'ed Yesod app scaffold to use
lambdacms-core to a fresh Yesod application scaffold, a number
of files need to be edited. We use some patch files to automate this
process to a couple of simple shell commands.
Run the following commands from the root of your Yesod application scaffold.
It first downloads the patches by cloning the repository in to the
directory. Then the patches are applied with the good old
export TMP_CLONE=/tmp/lambdacms-clone-for-patches-`date +%s` git clone --depth=1 https://github.com/lambdacms/lambdacms.git $TMP_CLONE mv $PROJECT_NAME.cabal project_name.cabal for f in $TMP_CLONE/yesod-scaffold-patches/*.patch; do patch -p1 < $f; done mv project_name.cabal $PROJECT_NAME.cabal rm -rf $TMP_CLONE
If any patches (partly) fail: try to fix it manually editing the files in question. If this happens while closely following this README, then please open an issue.
You could patch the files individually by manually unrolling the
in the commands above.
In some cases you may want to do manual patching instead (e.g. for existing web
app), in this case you can simply go through
.patch files in
lambdacms/yesod-scaffold-patches/ subfolder, they are quite self-exlplanatory.
Alternatively there is a
Configure the initial administrator
By default the application uses Mozilla's Persona to log in: the email address used to log in need to be registered with Persona. It is recommended to use an email address of a Persona account for development as it simplifies logging in during development.
config/settings.yml to insert a valid email address.
admin: "_env:LAMBDACMS_ADMIN:<email address>"
<email address> with the email address of an initial administrator
or developer, so the admin inteface can be accessed.
After applying the patches
lambdacms-core is installed in your Yesod application.
stack install again to rebuild and install with the patches.
Then start the development server, which automatically recompiles when files have changed.
stack exec yesod devel
Point your browser to
http://localhost:3000/admin and you will be
prompted to login. The setup as described above has selected Mozilla's
Persona as the only means of authentication. In
you have provided an email address for the admin user that is created
if no users exist. If this email address is known to Mozilla Persona
then you can procede to log in.
3. Add a LambdaCms "extensions" to your base application
LambdaCms' extension system is one of its core strengths: it allows a developer to extend the site with packages while ensuring full type safety.
Please refer to
for installation instructions. It also explains how other LambdaCms extensions
may incorporate media items managed by the
Or of course create your own extension...
4. Creating your own extensions
In order to make the code base of your website as modular as possible, we recommend packaging functionality into LambdaCms extensions. This allows functionality to be shared as a library.
Since this takes a bit of boiler plate, we have released a well documented extension scaffold script that should get you started.
We plan to have more reference material online soon.
Currently the best place to have a look is
the code for the lambdacms.org website.
It shows how a "base" application is extended with
All code in this repository is released under the MIT license, as specified in the LICENSE file.