/ 
Strehler-1.6.8
River stage one • 2 direct dependents • 2 total dependents
/ Strehler::Manual::Installation

NAME

Strehler::Manual::Installation - How to install Strehler

DESCRIPTION

A guide to install Strehler on your Dancer2 app and enjoy all the power of a ready-to-use general purpose CMS.

GETTING THE MODULE

Strehler module can be easly installed from CPAN

cpan -i Strehler

Strehler has Dancer2 as a mandatory dependency so getting it will give you all the tools to create a Dancer2 app (including Dancer2::Plugin::DBIC).

INSTALLING ON A DANCER2 APP

This tutorial needs a Dancer2 app already create and, generally speaking, is intended for users with some knowledge about Dancer2 framework. Strehler is a ready-to-use package, but it's still a toy for developers.

DATABASE

Dancer2 app needs a database. Connection will be managed by Dancer2::Plugin::DBIC so database's configuration has to be inserted in config.yml.

plugins:
    DBIC:
        default:
            dsn: dbi:mysql:mydb
            schema_class: Strehler::Schema
            user: myuser
            pass: mypassword
            options:
                RaiseError: 1
                PrintError: 1
                mysql_enable_utf8: 1

As you can see you can directly use Strehler::Schema as your schema_class. This is the fastest solution and the recommended one if you won't modify the database adding tables other than the ones used by Strehler.

With the configuration of your database in the config.yml you can run (from the root directory of your project):

strehler initdb

This script will create on your database all the tables needed by Strehler, asking you, during the procedure, to choose a password for your admin user.

BEWARE: All the tables will be preceded by a DROP IF EXIST command, so if ou run the command on a database where a Strehler table is present that will be destroyed and recreated. DO NOT USE this script to update the database from a Strehler version to another.

After using initdb command, if you chose to not use Strehler::Schema you can dump the schema using dbicdump from DBIx::Class::Schema::Loader.

TEMPLATE ENGINE

Strehler uses Template Toolkit as template engine. Configure it in your config file this way:

engines:
    template:
        template_toolkit:
            ENCODING: utf8
            DEFAULT: 'no.tt'
template: "template_toolkit"

STATIC CONTENTS

Static contents (css and javascript) must be copied in the public directory of the project to make them available.

In the root directory of the project type

strehler statics

This will copy under your public directory a strehler directory containing all the elements needed by the CMS.

strehler statics will erase the public/strehler directory every time you'll call it, to replace it with a fresh one from the package. Please, don't use this directory for your custom elements if you want to use this script also to update resources after a Strehler package update.

Note: You can launch initdb and statics toghere with the command

strehler batch

CONFIG.YML

Strehler needs something configured in your config.yml file. All informations about configuration is here https://github.com/cym0n/strehler/wiki/Configuration. The snippet below represent the minimal code needed to run CMS.

Strehler:
    languages: ['it']
    default_language: 'it'
    timezone: 'Europe/Rome'

Yes, i'm italian and the configuration follows my needs. :-)

APP.PL SCRIPT

In the bin/app.pl script just add

use Strehler::Admin;

This directive must be placed after the use directive for your main site module, as in the example below:

#!/usr/bin/env perl

use FindBin;
use lib "$FindBin::Bin/../lib";

use Site;
use Strehler::Admin;

Site->dance;

DANCER_CONFDIR

It's necessary to set environment variable DANCER_CONFDIR to make Strehler work correctly. Value of this variable must be the directory where your config.yml is (usually your siteroot). The directory must be written as absolute path.

There are many ways to do this. Some of them are listed here:

DIRECTLY IN THE APP.PL SCRIPT

You can configure it just in your app.pl script, remember to use require keyword instead of use to load Strehler modules and put variable declaration before requires.

#!/usr/bin/env perl

use FindBin;
use lib "$FindBin::Bin/../lib";

$ENV{DANCER_CONFDIR} = 'my/conf/dir';
require Site;
require Strehler::Admin;

Site->dance;

AS SHELL ENVIRONMENT VARIABLE

You can follow standard methos for environment configuration, declaring in in your .profile

DANCER_CONFDIR=my/conf/dir

or directly on the command line, when running the script

DANCER_CONFDIR=my/conf/dir perl bin/app.pl

In my opinion this is the less elegant way to do this.

IN YOUR UWSGI.CONF

If you're running site under uwsgi, just configure it in the uwsgi.conf adding an env line.

env = DANCER_CONFDIR=my/conf/dir

DANCE WITH STREHLER

Run your site, go to yourdomain.com/admin, enter admin as username and the password you chose during database init and enjoy Strehler!

DEMO

You can just try Strehler without creating a Dancer2 app and with very little Dancer2 knowledge using the demo command of the strehler script. Just type:

strehler demo

A complete Dancer2 app with Strehler installed will be created in a directory named StrehlerDemo. Now type:

cd StrehlerDemo
bin/app.pl

Open your browser and go to http://localhost:3000/admin. Enter admin as username and admin as password then try out all the Strehler feature as in a real site.