Built with Apache Lenya

Creating a New Publication

Table of Contents

Introduction
Prerequisites
Telling Lenya about Your Publication
Basic Configuration
Access Control Configuration
Configuring the Search Index
Deploying Your Publication
Next Steps

Introduction

In this tutorial, we guide you through the first steps on the way to your own publication. We assume that the publication is based on Lenya's default publication, at least until your standing firmly on your own feet.

Prerequisites

We'll use the following directory layout:

$HOME/
  apache/
    lenya-2.0/             The Lenya installation directory, we'll call it $LENYA_HOME.
  src/
    lenya/                 The home directory of your Lenya-related sources.
      pubs/                Your publications.
        $MYPUB/            Your first publication. We'll call this directory $MYPUB_HOME.
      modules/             Your modules.
      data/                Here you'll store your data:
        content/           Content (documents, images, ...)
        access-control/    Access control data
          passwd/          Users, groups, etc.
          policies/        Policies (page permissions)

By telling Lenya to store the data in your source tree and not in the web application context, you can more easily sync it with your source code repository.

To speed up your development, we recommend to serve the contents of modules directly from their sources. Edit your $LENYA_HOME/local.build.properties and update the modules.copy setting:

modules.copy=false

If you're using Eclipse, you can add a Java project with the src directory as home directory. We recommend to add the Lenya project to Eclipse as well so you can easily use it's API.

Telling Lenya about Your Publication

First, we have to tell Lenya that you want to deploy your publication. This is done in $LENYA_HOME/local.build.properties. Add the path to the directory where you store your publications to pubs.root.dirs:

pubs.root.dirs=src/pubs:/home/john/src/lenya/pubs

If you add multiple publications to this directory, Lenya will detect them automatically.

Basic Configuration

Now it's time to add the main configuration file of your publication, $MYPUB_HOME/config/publication.xml. The language settings depend on your requirements, you can add whatever languages you need. But make sure to use the official ISO 639-1 language codes. The entry <template id="default"/> tells Lenya that your publication is based on the default publication.

Here's an example how your publication.xml file might look like:

<?xml version="1.0" encoding="UTF-8"?>
<publication xmlns="http://apache.org/cocoon/lenya/publication/1.1">
  
  <name>My First Publication</name>
  <version>2.0-dev</version>
  <lenya-version>2.0-dev</lenya-version>
  <cocoon-version>2.1.10</cocoon-version>
  
  <languages>
    <language default="true">en</language>
    <language>de</language>
  </languages>
  
  <template-instantiator name="default"/>
  <path-mapper>org.apache.lenya.cms.publication.DefaultDocumentIdToPathMapper</path-mapper>
  <document-builder name="default"/>
  <site-manager name="tree"/>
  
  <template id="default"/>
  
  <content-dir src="/home/john/src/lenya/data/content"/>
  
  <resource-types/>
  <modules/>
  <proxies/>
 
</publication>

Access Control Configuration

The access control options are configured in $MYPUB_HOME/config/access-control/access-control.xml. We'll change the paths where access control data are stored:

<?xml version="1.0" encoding="UTF-8"?>
<access-controller type="bypassable">
  
  <accreditable-manager type="file">
    <parameter name="directory"
               value="/home/john/src/lenya/data/access-control/passwd"/>
    <user-manager>
      <user-type class="org.apache.lenya.ac.file.FileUser" create-use-case="admin.addUser"> 
        Local User</user-type>
    </user-manager>
  </accreditable-manager>
  
  <policy-manager type="document">
    <policy-manager type="file">
      <parameter name="directory"
                 value="/home/john/src/lenya/data/access-control/policies"/>
    </policy-manager>
  </policy-manager>
  
  <authorizer type="usecase">
    <parameter name="configuration"
      value="aggregate-fallback://config/access-control/usecase-policies.xml"/>
  </authorizer>
  
</access-controller>

Now we copy the role files (*.rml, where "rml" means "role markup language") from the default publication to our data/access-control/passwd directory:

$HOME/src/lenya/data/access-control/passwd/
  admin.rml
  edit.rml
  review.rml
  session.rml
  sitemanager.rml
  visit.rml

To be able to log in for the first time, we'll create a superuser account. Add the file data/access-control/passwd/admin.iml ("iml" means "identity markup language"):

<?xml version="1.0" encoding="UTF-8"?>
<identity id="admin" class="org.apache.lenya.ac.file.FileUser">
  <name>Administrator</name>
  <description></description>
  <email>admin@yourcompany.com</email>
  <password type="md5">8e07dafd13495561db9063ebe4db4b27</password>
  <groups>
    <group>administrators</group>
  </groups>
</identity>

The encrypted password is copied from the default publication's lenya user, the cleartext is levi.

We want to do it properly, so we add an administrators group (passwd/administrators.gml):

<?xml version="1.0" encoding="UTF-8"?>
<group class="org.apache.lenya.ac.file.FileGroup" id="administrators"/>

Each publication has an introduction page (introduction.html). We'll add a policy allowing everyone to visit the page. The file is located at data/access-control/policies/introduction.html/subtree-policy.acml:

<?xml version="1.0" encoding="UTF-8"?>
<policy xmlns="http://apache.org/cocoon/lenya/ac/1.0">
  <world>
    <role id="visit"  method="grant"/>
  </world>
</policy>

Finally, we have to add a policy for the authoring environment (data/access-control/policies/authoring/subtree-policy.acml), granting all roles to the administrators group:

<?xml version="1.0" encoding="UTF-8"?>
<policy xmlns="http://apache.org/cocoon/lenya/ac/1.0">
  <group id="administrators">
    <role id="edit"  method="grant"/>
    <role id="review"  method="grant"/>
    <role id="admin"  method="grant"/>
  </group>
</policy>

Configuring the Search Index

It is necessary to configure the search indexes for each publication. Add the file $MYPUB_HOME/config/search/lucene_index.xml. Here is an example - be sure to replace $MYPUB with the name of your publication everywhere!

<?xml version="1.0" encoding="UTF-8"?>
<indexes>
  <index id="$MYPUB-live" analyzer="stopword_en"
    directory="lenya/pubs/$MYPUB/work/lucene/index/live/index">
    <structure>
      <field id="url" type="keyword" />
      <field id="title" type="text" storetext="true"/>
      <field id="description" type="text" storetext="true"/>
      <field id="subject" type="keyword" storetext="true" />
      <field id="body" type="text" storetext="true"/>
    </structure>
  </index>
  <index id="$MYPUB-authoring" analyzer="stopword_en"
    directory="lenya/pubs/$MYPUB/work/lucene/index/authoring/index">
    <structure>
      <field id="url" type="keyword" />
      <field id="title" type="text" storetext="true"/>
      <field id="description" type="text" storetext="true"/>
      <field id="subject" type="keyword" storetext="true" />
      <field id="body" type="text" storetext="true"/>
    </structure>
  </index>
  <index id="$MYPUB-trash" analyzer="stopword_en"
    directory="lenya/pubs/$MYPUB/work/lucene/index/trash/index">
    <structure>
      <field id="url" type="keyword" />
      <field id="title" type="text" storetext="true"/>
      <field id="description" type="text" storetext="true"/>
      <field id="subject" type="keyword" storetext="true" />
      <field id="body" type="text" storetext="true"/>
    </structure>
  </index>
  <index id="$MYPUB-archive" analyzer="stopword_en"
    directory="lenya/pubs/$MYPUB/work/lucene/index/archive/index">
    <structure>
      <field id="url" type="keyword" />
      <field id="title" type="text" storetext="true"/>
      <field id="description" type="text" storetext="true"/>
      <field id="subject" type="keyword" storetext="true" />
      <field id="body" type="text" storetext="true"/>
    </structure>
  </index>
</indexes>

Deploying Your Publication

To deploy your publication, open a shell, go to the directory $LENYA_HOME and execute the build process:

$ cd ~/apache/lenya-2.0
$ ./build.sh

Wait until the build process is finished, and start the Jetty server using the command

$ ./lenya.sh

To check if Lenya found and deployed our publication correctly, open your browser and go to the URL http://localhost:8888. In the list at the left-hand side of the page you should see the entry "My First Publication". If not, Lenya didn't find your publication. Double-check the path in local.build.properties.

Click on the "My First Publication" link. The introduction page of your publication appears. Click on the link "Login as Editor". Login with the username admin and the password levi.

Now a page with the title "First Steps" should appear, asking you to either import the example content of the default publication, or start with your own homepage. We'll do the latter.

Click on the button Start with own page. You'll be asked to fill in a form. Enter "Home" as the page title, and select homepage as the resource type. Click the Create button. Congratulations, you've created your first page!

To make sure your content directory is configured properly, take a look at the data/content directory. Lenya should have created an authoring directory with some content in it.

Next Steps

Now you can go on with customizing your publication:

Add groups, users, and policies
Customize the layout by overriding the default publication XSLTs
Add more content
...