, _
/ _, _ / _/ _, / ) _ _,
(__ (/ //) () (/ (/ (__ //)_)
developer friendly :: type safe :: performant
Rationale
LambdaCms is a bunch of packaged libraries, containing sub-sites for the
Yesod application framework, which allow rapid
development of robust and highly performant websites with content management
functionality.
The lambdacms-*
packages each provide some functionality and can depend
on eachother as they depend on other packages.
The only mandatory package is lambdacms-core
(this package), it provides
functionality that all other lambdacms-*
packages can rely on.
As mentioned, each lambdacms-*
package contains a sub-site which is
"mounted" in a standard Yesod application, which we will refer to as
"the base application" or simply "base".
Before a packaged sub-site can be mounted, the package needs to be
included as a dependency to the base app's .cabal
file. After that
some glue code needs to be added to the base app, as explained below.
In the base app we have to:
- organize the main menu of the admin backend,
- configure a the database connection,
- specify the authentication strategies, and
- define admin user roles and their permissions.
In the base app we may optionally 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).
Getting started
Using this guide you will create a CMS website named mysite
.
For a real project you want to substitute this name, but for trying
out LambdaCms it is recommended to keep it for the convenience of
copy-pasting the instructions that follow.
Prerequisites
You need to be reasonably acquinted with Haskell in order to follow
along with this guide. To learn basic Haskell skill 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),
- SQL (as LambdaCms makes use of a relational database), and
- the Yesod web application framework (book).
Make sure to have GHC 7.8.3+, cabal-install 1.20+, happy, alex
, yesod-bin 1.4.3.3+ installed, and their binaries available from your
shell's $PATH
.
To check that you are good to go, you can use these commands.
ghc -V
cabal -V
happy -V
alex -V
yesod version
In case you are not good to go, you may want to follow the
installation guide on the Stackage website
which provides instructions for all dependencies except yesod-bin
.
Once you meet all the requirements except yesod-bin
, install it.
cabal install "yesod-bin >= 1.4.3.3"
Required non-Haskell dependencies
For the connection with the database, Haskell libraries typically compile
against non-Haskell libraries. One of the following libraries needs to be
available:
- For Postgres:
- Ubuntu:
libpq-dev
- Homebrew on OSX:
postgres
- For Mysql:
- Ubuntu:
libmysqlclient-dev
- Homebrew on OSX:
mysql
- For Sqlite
- Ubuntu:
libsqlite3-dev
- Homebrew on OSX:
sqlite
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, you also need
to install that.
Create the base application
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
After scaffolding cd
into the project folder.
If you have chosen a database other than Sqlite, you need to create a
database and a sufficiently priviledged user, and supply the
credentials to the config/setting.yml
file.
Using LTS Haskell
To avoid spending too much time on build issues we use and recommend
LTS Haskell.
Currently we develop and test LambdaCms only against the lastest
LTS Haskell release. As minor releases of LTS Haskell should never
contain breaking changes we only provide the major release number,
thereby automatically using the most recent minor release in that
series.
Run the following commands from within your project's root folder,
to install the most recent LTS Haskell package set in the 1.x
series.
wget http://www.stackage.org/lts/1/cabal.config
cabal update
The install all dependencies and build your application with (this
may take a while the first time you run it).
cabal install --enable-tests . --max-backjumps=-1 --reorder-goals
In case you experience problems with cabal install
try adding
-j1
as a flag (prevents concurrent building).
When you experience problems during builds, while using LTS 1.x
,
we consider this a bug. Please
raise an issue.
The following commands will run your scaffolded Yesdo application
in development mode.
yesod devel
Now test it by pointing the browser to localhost:3000
.
If all went well you are ready to add LambdaCms to your app.
Add LambdaCms
LambdaCms is on Hackage! Install with: cabal install lambdacms-core
In the following sub-sections we explain how to install lambdacms-core
into
the base application. Much of what we show here can be accomplished in
many different ways, in this guide we merely provide a way to get you started.
Patching a new Yesod application
To setup a new LambdaCms website the easy way we created patch files to convert
a new Yesod application to a LambdaCms website. Those patches can be found in
lambdamcs-patches. Either clone
the repository or copy only the required patches to your local environment and
run the following command (replace /path/to
with the actual path to the patch
file):
patch -p1 < /path/to/lambdacms.patch
This patches all files at the same time. Documentation about how to patch files
individually can be found in the lambdacms-patches
README.
To manually add LambdaCms to a Yesod application follow the steps below.
Modify the .cabal
file
First add lambdacms-core
to the dependencies list of the .cabal
file (name of the file depends on the name of your project).
Add the follwing to the end of the build-depends
section:
, lambdacms-core >= 0.0.7 && < 0.1
, wai >= 3.0.2 && < 3.1
And add the following line to the library/exposed-modules
section:
Roles
Modify the config/routes
file
Replace all of the file's content with:
/static StaticR Static appStatic
/favicon.ico FaviconR GET
/robots.txt RobotsR GET
/ HomeR GET
/admin/auth AuthR Auth getAuth
/admin/core CoreAdminR CoreAdmin getLambdaCms
/admin AdminHomeRedirectR GET
Modify Settings
There are two files to modify here. One is config/settings.yml
and the the other is Settings.hs
.
In config/settings.yml
, add the following line to the bottom of the file
admin: "_env:LAMBDACMS_ADMIN:<your email address>"
Then, in Settings.hs
, append the following record to the AppSettings
data type:
, appAdmin :: Text
In instance FromJSON AppSettings
, find this line:
Add the following line just before the line containing return AppSettings {..}
:
appAdmin <- o .: "admin"
Modify the config/models
file
Replace all of the file's content with the following UserRole
definition:
UserRole
userId UserId
roleName RoleName
UniqueUserRole userId roleName
deriving Typeable Show
Modify the Model.hs
file
Add the following imports:
import Roles
import LambdaCms.Core
Modify the Application.hs
file
Add the following imports:
import LambdaCms.Core
import LambdaCms.Core.Settings (generateUUID)
import Network.Wai.Middleware.MethodOverridePost
Add the following function:
getAdminHomeRedirectR :: Handler Html
getAdminHomeRedirectR = do
redirect $ CoreAdminR AdminHomeR
In the makeFoundation
function, add this line to beginning:
let getLambdaCms = CoreAdmin
Then, find this code:
-- Perform database migration using our application's logging settings.
runLoggingT (runSqlPool (runMigration migrateAll) pool) logFunc
-- Return the foundation
return $ mkFoundation pool
And replace it with:
-- Perform database migration using our application's logging settings.
let theFoundation = mkFoundation pool
runLoggingT
(runSqlPool (mapM_ runMigration [migrateAll, migrateLambdaCmsCore]) pool)
(messageLoggerSource theFoundation appLogger)
-- Create a user if no user exists yet
let admin = appAdmin appSettings
madmin <- runSqlPool (getBy (UniqueEmail admin)) pool
case madmin of
Nothing -> do
timeNow <- getCurrentTime
uuid <- generateUUID
flip runSqlPool pool $ do
uid <- insert User { userIdent = uuid
, userPassword = Nothing
, userName = takeWhile (/= '@') admin
, userEmail = admin
, userActive = True
, userToken = Nothing
, userCreatedAt = timeNow
, userLastLogin = Nothing
, userDeletedAt = Nothing
}
-- assign all roles to the first user
mapM_ (insert_ . UserRole uid) [minBound .. maxBound]
_ -> return ()
-- Return the foundation
return theFoundation
In the function makeApplication
replace this line:
return $ logWare $ defaultMiddlewaresNoLogging appPlain
With this line (adding a WAI middleware is needed to make RESTful
forms work on older browsers):
return $ logWare $ methodOverridePost appPlain
Create the Roles.hs
file
Create the Roles.hs
file (in the root directory of your
application) and add the following content to it:
module Roles where
import ClassyPrelude.Yesod
data RoleName = Admin
| Blogger
deriving (Eq, Ord, Show, Read, Enum, Bounded, Typeable)
derivePersistField "RoleName"
Modify the Foundation.hs
file
Add the following imports:
import qualified Data.Set as S
import qualified Network.Wai as W
import LambdaCms.Core
import Roles
Append the following record to the App
data type:
, getLambdaCms :: CoreAdmin
Change the implementation of isAuthorized
(in instance Yesod App
) to the
following, which allows fine-grained authorization based on UserRoles
:
isAuthorized theRoute _ =
case theRoute of
(StaticR _) -> return Authorized
(CoreAdminR (AdminStaticR _)) -> return Authorized
_ -> do
mauthId <- maybeAuthId
wai <- waiRequest
y <- getYesod
murs <- mapM getUserRoles mauthId
return $ isAuthorizedTo y murs $ actionAllowedFor theRoute (W.requestMethod wai)
Change the implementation of getAuthId
(in instance YesodAuth App
) to:
getAuthId = getLambdaCmsAuthId
In instance YesodAuth App
replace:
loginDest _ = HomeR
logoutDest _ = HomeR
With:
loginDest _ = CoreAdminR AdminHomeR
logoutDest _ = AuthR LoginR
And add:
authLayout = adminAuthLayout
Add the following instance to allow Unauthenticated
GET
requests for the
HomeR
route (likely to be /
) and other common routes such as /robots.txt
.
The last pattern allows access to any unspecified routes for just Admins -- which is a role defined in Roles.hs.
It is in actionAllowedFor
that you will setup permissions for the roles.
instance LambdaCmsAdmin App where
type Roles App = RoleName
actionAllowedFor (FaviconR) "GET" = Unauthenticated
actionAllowedFor (RobotsR) "GET" = Unauthenticated
actionAllowedFor (HomeR) "GET" = Unauthenticated
actionAllowedFor (AuthR _) _ = Unauthenticated
actionAllowedFor _ _ = Roles $ S.fromList [Admin]
coreR = CoreAdminR
authR = AuthR
masterHomeR = HomeR
-- cache user roles to reduce the amount of DB calls
getUserRoles userId = cachedBy cacheKey . fmap toRoleSet . runDB $ selectList [UserRoleUserId ==. userId] []
where
cacheKey = encodeUtf8 $ toPathPiece userId
toRoleSet = S.fromList . map (userRoleRoleName . entityVal)
setUserRoles userId rs = runDB $ do
deleteWhere [UserRoleUserId ==. userId]
mapM_ (insert_ . UserRole userId) $ S.toList rs
adminMenu = (defaultCoreAdminMenu CoreAdminR)
renderLanguages _ = ["en", "nl"]
mayAssignRoles = do
authId <- requireAuthId
roles <- getUserRoles authId
return $ isAdmin roles
Add an isAdmin
function to the bottom of Foundation.hs
Remember that the Admin
role is defined in Roles.hs
isAdmin :: S.Set RoleName -> Bool
isAdmin = S.member Admin
Give it a try
LambdaCms should now be installed. You can give it a try.
yesod devel
Now 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 config/settings.yml
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.