redarrow

Part 2: Installing Lenya

29 January 05

So here you are, ready to install the mysterious Lenya. If you haven't already, I encourage you to take a quick gander at Part I: Understanding Lenya to make sure you know what you are getting into before attempting this install. Also, some knowledge in the basics of using a UNIX/Linux operating system are assumed. So without further delay, let's kick it!

Requirements

OK, I do have to mention one thing: while you can install Lenya on Windows, I'm going to be taking you through a Linux installation. For Windows help, I'll have to direct you to the user mailing lists.

I also recommend a broadband connection, especially for downloading Cocoon (approx. 43 MB) and the Java SDK (approx. 35 MB), but if you want to sit around and wait while they download on a phone line, be my guest!

1. Linux/UNIX (I'm using RedHat Enterprise AS, but any Linux will do)
2. Java 1.4.2 SDK (I downloaded the RedHat RPM)
3. Cocoon 2.1.6 (the TAR/GZ source version)
4. Lenya 1.2.1 (the tar.gz source version is what I am using, under the SOURCES directory)
5. (optional) Tomcat 5.0.28 (the binary tar.gz version)

Why is Tomcat optional? Well, because Lenya already comes with a servlet container called Jetty. Both Jetty and Tomcat are the servlet containers tested with Lenya, and since we're using Tomcat for Hiram's site, that's what I'll be taking you through. For brief instructions on using Jetty, read the tutorial on Lenya's site.

It's also assumed that the first steps before switching to our new user in step 5 are done with a user that has the capabilities of installing Java and the like. I used the root user to do the installs and moves, then switched to the our new user for the rest.

10 Steps to Lenya bliss

Step 1: Download!

Yeah, seems simple enough, doesn't it? Get 2-5 from above downloaded and on the server you'll be using.

Step 2: Install Java SDK

If you downloaded the RPM, you'll need to execute the file first. It spits out the Licensing Agreement, for which you must agree to, and then your RPM file is ready. To install on RedHat, type in the following:

rpm -ivh j2sdk-1_4_2_07-linux-i586.rpm

or whatever your RPM file happens to be named. This should install your Java files in /usr/java/ by default. You'll also need to setup some environment variables for Java in order for Tomcat to start up correctly later on. Again, these instructions are for RedHat, so consult documentation for your OS if need be.

cd /etc/profile.d/

Create a new file called java.sh and fill it with the following for now:

export JAVA_HOME=/usr/java/java
export PATH=$PATH:$JAVA_HOME/bin
export CLASSPATH=$JAVA_HOME/lib:$JAVA_HOME/jre/lib/ext

Save it and exit from the file. While we are here, let's add the rest of the environment variables for the other applications. So, for Tomcat, create a new file called tomcat.sh and add the following inside:

export CATALINA_HOME=/usr/local/tomcat
export PATH=$PATH:$CATALINA_HOME/bin

Save and exit. Then, create a new file called webapps.sh and add the following inside:

export LENYA_HOME=/home/webapp/web_software/lenya-1.2.1
export COCOON_HOME=/home/webapp/web_software/cocoon-2.1.6
export COCOON_WEBAPP=/home/webapp/web_software/cocoon-2.1.6/build/webapp

Save and exit.

Step 3: Setup a new user

You'll want to create a new user that has access to all of the Cocoon, Tomcat, and Lenya files. I'll call the user "webapp". In most Linux distributions, you can use the graphical tools to add a new user, or if you are a die-hard command-line junkie, use the following command in RedHat to add our new user:

useradd -c "Web Applications" -m webapp

This basically sets up a new user with the name of "Web Applications", a username of "webapp" and creates a home directory (the -m switch) with the standard initialization files.

You may want to setup a password for this user. To do that, simply do this:

passwd webapp

It will prompt you for the new password twice. Assuming you typed it in the same way both times, you're all set! This is only basic, so if you want to add password expiration options, etc., go right ahead!

Step 4: Move downloads to right places

In most UNIX/Linux systems, webapp's home directory should be /home/webapp/. Inside webapp's home directory, we'll create a new directory to store our source files. Let's call it "web_software":

mkdir /home/webapp/web_software
chown -R webapp:webapp /home/webapp/web_software

Go ahead and move both Lenya's and Cocoon's zipped up files to that directory (you'll have to change to the directory that your downloaded files are stored first):

mv apache-lenya-1.2.1-src.tar.gz /home/webapp/web_software/
mv cocoon-2.1.6-src.tar.gz /home/webapp/web_software/

Tomcat needs to go in /usr/local/ (at least that's the typical place for it):

mv jakarta-tomcat-5.0.28.tar.gz /usr/local/

Step 5: Change permissions of files

Now that you created that webapp user, you'll want to assign permissions to the Lenya, Cocoon, and Tomcat files to webapp:

chown webapp:webapp /usr/local/jakarta-tomcat-5.0.28.tar.gz
chown -R webapp:webapp /home/webapp/web_software/

And then switch to that user:

su - webapp

Step 6: Unzip Lenya

Pretty easy stuff:

cd web_software
tar xzvf apache-lenya-1.2.1-src.tar.gz
mv apache-lenya-1.2.1-src lenya-1.2.1

Step 7: Unzip and build Cocoon

Same deal here:

tar xzvf cocoon-2.1.6-src.tar.gz
mv cocoon-2.1.6-src cocoon-2.1.6

Now, you'll need to copy some config files from Lenya into Cocoon's directory:

cp lenya-1.2.1/local.build.properties cocoon-2.1.6/
cp lenya-1.2.1/local.blocks.properties cocoon-2.1.6/

Then the all-important part, compiling Cocoon. It's this simple:

cd cocoon-2.1.6
./build.sh -Dinclude.webapp.libs=yes webapp

Step 8: Install Tomcat

Since we downloaded the binary version of Tomcat, there's not much to do except to unzip the files. So here we go again:

cd /usr/local/
tar xzvf jakarta-tomcat-5.0.28.tar.gz

Since that name is rather long, let's create a link to it:

ln -s jakarta-tomcat-5.0.28 tomcat

Step 9: Configure and install Lenya

OK, we need to let Lenya know where Tomcat is before we install it.

cd /home/webapp/web_software/lenya-1.2.1/
cp build.properties local.build.properties

Inside this file, you'll need to change a couple of things. Below are the lines you'll need to change in local.build.properties, so scope them out in the file, make the changes, and save them:

cocoon.src.dir=../cocoon-2.1.6
tomcat.home.dir=/usr/local/tomcat
enable.uploads=true

Once done, we'll need to compile:

./build.sh install

Step 10: Start up Tomcat

To start Tomcat, simply type in the following:

/usr/local/tomcat/bin/startup.sh

Getting your first access to Lenya

Now that Tomcat is up, you should be able to access Lenya pretty easily. Just go to the following URL: http://your.server.url:8080/lenya/. You should see a couple of publications listed on the left with general information about Lenya. From there, you can log into the Default Publication with the username "lenya" and the password "levi".

Next Article

Now that you have the basic installation done, play around and have some fun. In the next article, we'll take a look at how pages are created, published, and customized by changing some of the files in the Default Publication as well as creating our own pipeline. Feel free to post here if you run into any problems during the installation, and I'll try my best to help out.