<application class="software">MMBase</application> Installation HOWTO
AdrianOffermantldp@NOSPAM.offerman.net2003 - 2006Adrian OffermanJune 25, 2006minor corrections0.3.52006-06-25AOTomcat init script0.3.42005-09-18AOminor corrections0.3.22005-01-25AOMMBase 1.7.3, Java 1.5.0-010.3.12004-12-26AOEmail module0.3.02004-12-25AOMMBase 1.7.2, Tomcat 5.5.4, Java 1.5.0, MySQL Connector/J 3.0.16-ga, Jikes 1.220.2.62004-07-27AOminor additions0.2.52004-02-28AOCreative Commons copyright license adjusted0.2.42004-01-22AOCreative Commons copyright license; minor additions and corrections0.2.32003-12-26AOminor additions and corrections0.2.22003-12-20AOcopyright adjusted0.2.12003-12-18AOminor corrections0.2.02003-12-15AOJK 2 Connector setup added0.1.02003-12-10AOinitial draft
This document describes the installation of the
MMBase
content management system
on a Red Hat Linux distribution,
using the Tomcat application
server,
and integrating it with MySQL
and Apache.
This document describes the installation of the
MMBase content management system
on a Red Hat Linux distribution,
using the Tomcat application
server,
and integrating it with MySQL
and Apache.
Version: 0.3.5; June 25, 2006.
Author: Adrian Offerman
The latest version of this document can be found at:
http://www.offerman.net/MMBase-Installation-HOWTO/
Feedback is welcome at:
http://www.offerman.net/MMBase-Installation-HOWTO/feedback.html
For questions, check out the
MMBase website:
http://www.mmbase.org/
You can find the
MMBase documentation at:
http://www.mmbase.org/docs/
Good luck!
Introduction
>From the MMBase website
(www.mmbase.org):
MMBase
is a Web Content Management System
with strong multimedia features.
MMBase
has a large installed base in The Netherlands,
and is used by major Dutch broadcasters, publishers, educational institutes,
national and local governments.
MMBase
is written in Java,
it is Open Source Software (MPL)
and all standards used are as 'open' as possible.
The system can be used with all major operating systems, application servers
and databases.
Unfortunately, the installation of
MMBase
is not well documented.
Furthermore, when searching the internet looking for installation clues
and trying out tips,
it turns out that the details of the installation have changed frequently.
This document describes the installation of the
MMBase content management system
on a Red Hat Linux distribution,
using the Tomcat application
server,
and the integration with MySQL
and Apache.
It is based on our own experience
and compiled to the benefit of the community.
These are the ingredients we used to cook up this recipe ourselves:
Red Hat 8.0 distribution
running a 2.4.20 kernel,
with Alan Cox 2
and
EA/ACL
extensions.
Java 2 Software Developers Kit (SDK)
and Java 2 Run-time Engine (J2RE)
from Sun's Java 2 Platform Standard Edition 5.0 (J2SE) (version 1.5.0-01),
Apache Jakarta Tomcat 5.5.4,
ImageMagick 6.1.3-7,
MMBase 1.7.3 with various modules,
MySQL Connector/J 3.0.16-ga,
Jikes 1.22.
And before:
Red Hat 8.0 distribution
running a 2.4.20 kernel,
with Alan Cox 2
and
EA/ACL
extensions.
Java 2 Software Developers Kit (SDK)
and Java 2 Run-time Engine (J2RE)
from the Blackdown Java 2 JDK version v1.4.1-01,
Apache Jakarta Tomcat 4.1.27,
ImageMagick 5.4.7-5,
MMBase 1.6.5 for JDK 1.4,
MySQL Connector/J 3.0.8,
Jikes 1.18.
Installation
Although we installed MMBase
on a kernel with the Alan Cox
and
EA/ACL
extensions,
these features are no prerequisites.
We assume that you have already installed and configured
Apache
and MySQL
on your server.
Installing <application class="software">Java</application>
Download the latest versions of the
Java 2 Development Kit
(JDK) or
Run-time Engine
(JRE),
and the accompanying documentation from:
http://java.sun.com
Installation instructions and release notes for the
JDK and
JRE
are available at the download page.
Make the binary distribution of the
JDK
executable
and extract in a new directory:
Install the JDK
documentation
by unzipping it in the
JDK directory:
Change the ownership of the
JDK directory
and make it available as
/usr/local/j2sdk/:
If you need only the
JRE,
the installation would be like this:
Using JDK
version 1.5.0 caused
our Tomcat server
to crash every now and then:
Upgrading to version 1.5.0-01 seemed to solve these problems.
For the (previously used)
BlackDown Java for Linux distribution:
Find yourself a mirror for the
BlackDown Java Development Kit
at:
http://www.blackdown.org/java-linux/mirrors.html
There you can download the latest versions of the
J2 Software Development Kit (SDK)
and
Run-time Engine (RE).
Make sure you pick out the right version for the
gcc library installed on your system.
You can find out the version currently installed by typing:
Installation instructions for the
Java Development Kit
are available as
INSTALL-j2sdk
and INSTALL-j2re.
Make the binary distribution of the
SDK
executable
and extract in a new directory:
Change the ownership of the
J2SDK
directory
and make it available as
/usr/local/j2sdk/:
Do the same for the
RE:
Since we didn't install the
JDK
and JRE
in our path,
we have to add the bin/ directories
to our $PATH environment variable.
To make sure the Java
distributions and classes can be found,
we set the $JAVA_HOME
and $CLASSPATH variables as well.
For the Bourne shells,
create a file /etc/profile.d/java.sh:
Set its ownership and access rights:
Do the same for C shells,
by creating the file
/etc/profile.d/java.csh:
and setting its ownership and access rights:
Now the JDK
should be available to everyone on your system.
You can test the Java engine
by typing:
or create a file Test.java:
and test the compiler:
Installing <application class="software">Tomcat</application>
Download a binary distribution of
Tomcat
from the Apache Jakarta website:
http://jakarta.apache.org/tomcat/
If you don't want to run the
Tomcat daemon as
root,
create a new user/group tomcat
(first make sure that the
UID and GID
you use
are still available
by checking the files /etc/passwd
and /etc/group):
You really should not use the
root account
to run the Tomcat daemon;
(using Tomcat version 4.1.27) we found out that this allows the
MMBaseadmin user
to write backup dumps of his sites anywhere on the system.
<TODO: better solution available?>
Extract the Tomcat distribution
in a new directory:
Version 4.1.27 came with a hot-fix:
Change the ownership of the
Tomcat directory
and make it available as
/usr/local/tomcat/:
Open up the firewall for web access
to the Tomcat server
by adding to the file
/etc/sysconfig/iptables:
You need to reboot your system to make this rule effective
or restart the iptables firewall:
Since (for some odd reason) some network managers allow outgoing web
connections only to
TCP port 80,
there might be people around that cannot access your
Tomcat
(and MMBase) server
through port 8080.
Further below
we will explain how to install
a JK 2 mapping or a reverse proxy
in Apache,
so Tomcat
and MMBase
can be accessed through the
Apache web server
at port 80.
Apart from the port issue,
this has the advantage that you can use
Apache
to manage you SSL connections
and use your existing
Apache
logs and statistics facilities
for Tomcat
and MMBase as well.
If you decide to use
Apache
as a front-end to your
Tomcat
and MMBase server,
there's no need to open up
port 8080
in your firewall.
To run Tomcat,
set the $CATALINA_HOME environment variable:
and fire it up:
Now you can access
Tomcat's home page through
(replace <hostname> with your hostname):
:8080/
]]>
which should give you the Tomcat
welcome screen.
600x420x256
To shutdown again:
Since we want to automate the starting up and shutting down of the
Tomcat server,
we create a file
/etc/rc.d/init.d/tomcat
to do this for us:
Set its ownership and access rights:
And add this init script to
chkconfig:
Instead of creating your own init script,
you can use the script that comes with
the Tomcat package:
/usr/local/tomcat/bin/catalina.sh.
Make sure you set
the Tomcat environment
at the start of this script.
Or create a short init script that calls
the original Tomcat init script.
See
How can I start Tomcat as a daemon in Linux?.
To install two (or even more) versions of
Tomcat server
on the same system,
increase the port numbers
of the second server (e.g. by 10),
by editing the configuration file
/usr/local/tomcat55/conf/server.xml:
...
...
...
...
]]>
Complete this second
Tomcat server installation
as above for the first server,
using adjusted directory and file names.
Replacing <application class="software">Tomcat</application>'s
default <acronym>JSP</acronym> compiler
<application class="software">Jasper</application>
with <acronym>IBM</acronym>'s
<application class="software">Jikes</application> compiler
Since IBM's
Java compiler
Jikes
is performing better than
Tomcat's own
JSP compiler
Jasper,
it's recommended to install
Jikes instead.
Download the sources of Jikes
from IBM's Research website:
http://jikes.sourceforge.net/
Extract and compile Jikes:
Check support for the option:
To have Jikes
output its error messages in a
Jasper compatible way,
add this $CATALINA_OPTS environment variable
to /etc/rc.d/init.d/tomcat:
If you get an error message saying
Jikes can not use
UTF8 encoding,
add the following option as well:
Make Jikes
your JSP compiler
for Tomcat
by adding to
/usr/local/tomcat/conf/web.xml:
compilerjikes
]]>
Since entering the full path to
Jikes
in /usr/local/tomcat/conf/web.xml
doesn't seem to work (version 4.1.27),
make the jikes program available in your path:
Installing <application class="software">ImageMagick</application>
MMBase
uses ImageMagick's
convert tool
to build and convert its images.
ImageMagick
is already part of the
Red Hat distribution.
Check its availability using:
If ImageMagick
is not available on your system,
install it
using up2date:
or download it from the Red Hat Network:
https://rhn.redhat.com/
and install it by hand:
Installing <application class="software">MMBase</application>
Download the binary distribution of
MMBase,
and the additional applications you need
(i.e. CloudContext Security,
Media,
Email)
(see the next section),
from:
http://www.mmbase.org/ --> Download --> Releases
MMBase version 1.7.2
contained a nasty bug,
resulting in problems with the editwizards.
The 1.7.3 release includes a bugfix for this problem.
Make sure you pick out the right version for the
Java 2 JDK
installed on your system.
You can find out the version currently installed by typing:
Extract the binary distribution of
MMBase,
copy it into the
Tomcat directory,
and change the ownership of the
MMBase directory:
Installing MMBase version 1.7
on Tomcat version 5
resulted in version incompatibilities:
We had to disable
the RMMCI library
to get this installation up and running:
For MMBase version 1.7
running on Tomcat version 5,
enable the Xerces libraries:
Or you will have fatal errors like:
For MMBase version 1.6
running on Tomcat version 4,
replace the TomcatXerces libraries
by those coming with MMBase:
If you will not be using an
Apache
JK 2 mapping or reverse proxy
(see further below)
as a front-end to your
MMBase server,
you can add to the file
/usr/local/tomcat/conf/server.xml:
]]>
This will allow you to access your
MMBase server
using
(replace <hostname> with your hostname):
:8080/mmbase
]]>
instead of:
:8080/mmbase-webapp
]]>
Check if the ImageMagickconvert tool
is in your path:
If not, add it to
/usr/local/tomcat/webapps/mmbase-webapp/WEB-INF/config/applications/Resources/builders/images.xml.
For example:
/usr/bin/X11/convert
]]>
Make sure that the directory
/usr/local/tomcat/webapps/mmbase-webapp/WEB-INF/config/builders/applications
is writable by the servlet engine user
(for auto-installing builders):
Connecting <application class="software">MMBase</application>
to <application class="software">MySQL</application>
using <systemitem class="library">MySQL Connector/J</systemitem>
We can connect
MMBase
to our MySQL database server
using MySQL Connector/J.
This JDBC driver
for MySQL
can be downloaded from:
http://www.mysql.com/downloads/api-jdbc.html
Copy the JDBC driver
to the MMBaselib/ directory:
Make this your JDBC driver
for MMBase
by editing
/usr/local/tomcat/webapps/mmbase-webapp/WEB-INF/config/modules/jdbc.xml.
Substitute the database name
(mmbase),
user (mmuser)
and password (mmpass)
with the database settings you'd like
MMBase to use.
jdbc:mysql://$HOST:$PORT/$DBM
mmusermmpassorg.mmbase.module.database.DatabaseSupportShimmmbase20localhostcom.mysql.jdbc.Driver330625630
]]>
Set the ownership and access rights of this configuration file.
Since it contains your database name, user name and password,
make sure other users can not read this file.
Now create the MySQL database
you've just defined for
MMBase:
;
USE ;
GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP ON .* TO
@'%' IDENTIFIED BY '';
GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP ON .* TO
@localhost IDENTIFIED BY '';
GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP ON .* TO
@localhost. IDENTIFIED BY '';
# RH bug fix
GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP ON .* TO
@ IDENTIFIED BY '';
flush privileges;
exit;
]]>
Substitute the hostname (<hostname>)
and domain name (<domainname>)
with your own hostname and domain name,
and the database name (<mmbase>),
user (<mmuser>)
and password (<password>)
with the values you just entered in the JDBC driver configuration file.
To quickly empty
your MySQL database,
i.e. after you've updated
your MMBase configuration or
application
(replace the database name <mmbase> with your
own):
mysqladmin -u root -p create
]]>
If you are already using quite some
MySQL connections
(for example for authentication by and as a back-end to your mail daemons
and Apache servers),
the MySQL server
might run out of connections (its maximum number defaults to 100).
Then Tomcat
could simply refuse to start or give an error message
when initiating the
MySQL connection pool,
or your IMAP
or POP servers will have
problems authenticating their clients.
You can increase the maximum number of connections
to MySQL
by adding to the configuration file
/etc/my.cnf:
Installing <application class="software">MMBase</application>
additional applications
With the release of version 1.7
MMBase
was reworked into a more modular structure.
The developers decided to take several modules
(i.e. CloudContext Security,
Media,
Email)
from the MMBase tree,
and make these available as separate entities.
However, at this moment
MMBase
doesn't have a module interface at all.
So, to use these additional applications,
the library and other files need to be placed into the installation tree
and the configuration needs to be added into the existing configuration files
by hand.
Installing
the <application class="software">CloudContext Security</application> module
>From the MMBase website
(www.mmbase.org):
Cloud security
uses the object mmbaseuser
to store information used for authorisation and authentication of users.
The two main advantages of this security implementation are
that the user administration can be carried out by using a webbrowser
(instead of editing a file on the filesystem) and
that the users of your
MMBase installation
are available as objects in the cloud.
For instance, it is possible to create groups of users,
which are allowed to carry out certain tasks.A context exists of a set of rights
which describe what you can do within this context
with an object of
MMBase.
For example you define read access to a the context
which is used by anonymous visitors of your site and
you can define a context with edit rights for registered users of your site.
Move the library and other files of
the CloudContext Security module
into the MMBase installation tree:
Save the documentation files for later reference:
Make sure all these new files are owned by
your tomcat user as well:
Disable the existing configuration
in the security configuration file
/usr/local/tomcat/webapps/mmbase-webapp/WEB-INF/config/security/security.xml:
-->
...
]]>
And add
(from web-app/WEB-INF/config/security/security.xml):
]]>
Make sure to include the configuration above before
the <sharedsecret> statement,
or you will get an error like this:
Installing
the <application class="software">Media</application> module
<TODO>
Installing
the <application class="software">Email</application> module
The Email module
makes it possible to send email
with MMBase,
using either SendMail
or JMSendMail.
Move the library and other files of
the Email module
into the MMBase installation tree:
Save the documentation files for later reference:
Make sure all these new files are owned by
your tomcat user as well:
Edit the email configuration file
/usr/local/tomcat/webapps/mmbase-webapp/WEB-INF/config/modules/sendmail.xml
(from web-app/WEB-INF/config/modules/sendmail.xml):
active
...
org.mmbase.applications.email.SendMail
...
]]>
Add to Tomcat's
root Context
(in /usr/local/tomcat/conf/context.xml for Tomcat version 5,
in /usr/local/tomcat/conf/server.xml for Tomcat version 4)
(replace <smtp.domain.tld> with the adres of your
SMTP server):
mail.smtp.hostsmtp.domain.tld
]]>
Failing to do this, results in a fatal error:
Installing the Email module
in MMBase version 1.7
running on Tomcat version 5
resulted in a fatal error:
Configuring initial
<application class="software">MMBase</application> settings
Here are some initial configuration settings
for MMBase.
Change the default password
admin2k
for the administrator admin
by editing
/usr/local/tomcat/webapps/mmbase-webapp/WEB-INF/config/security/context/config.xml:
admin2k
]]>
Also, outcomment or remove the user
foo/bar.
Since this file contains your administrators password,
make sure other users can not read it:
To use the MMBase
builder mmbaseuser
(using the mmbaseuser table
in your MySQL database)
for user authentication,
set the authentication class
in the configuration file
/usr/local/tomcat/webapps/mmbase-webapp/WEB-INF/config/security/security.xml
to:
]]>
and set the authorization class to:
]]>
In the same file change the shared secret used to communicate with remote
builders
(on other MMBase servers):
yoursharedsecret
]]>
You can set the language
for MMBase
by editing
/usr/local/tomcat/webapps/mmbase-webapp/WEB-INF/config/modules/mmbaseroot.xml:
en
]]>
You can set the SMTP gateway by editing
/usr/local/tomcat/webapps/mmbase-webapp/WEB-INF/config/modules/sendmail.xml:
localhost
]]>
Running <application class="software">MMBase</application>
Now you are ready to start Tomcat:
and access your new MMBase server
through
(replace <hostname> with your hostname):
:8080/mmbase-webapp/
]]>
If everything you just did worked out,
you should get the
MMBase welcome screen
where you can change the settings, look at the demos, and install the
samples.
600x415x256
When asked for a login use the name
admin
and the password
you just set in the security configuration file
/usr/local/tomcat/webapps/mmbase-webapp/WEB-INF/config/security/context/config.xml.
MMBase users
(i.e. front-end developers) will typically add their web files to
the /usr/local/tomcat/webapps/mmbase-webapp/ directory.
Applications (defining the content) will be placed in
the
/usr/local/tomcat/webapps/mmbase-webapp/WEB-INF/config/applications/
directory.
Tomcat
consumes far more CPU and memory resources
than Apache.
Make sure the dimensions of your
Tomcat/MMBase server system meet these requirements.
Shutting down (or restarting) the
Tomcat server (version 1.6)
in our case always left a last process running.
If you experience this same problem,
kill the process by hand before starting it up again:
You can save the original index.jsp file
by renaming it to mmbase.jsp:
This will allow you to always access the original MMBase home page through
(replace <hostname> with your hostname):
:8080/mmbase-webapp/mmbase.jsp
]]>
In case of any problems,
check the Tomcat
and MMBase log files
in the directory
/usr/local/tomcat/logs/
for hints.
>From here, we refer to the documentation
on the MMbase website
to complete your configuration
and start using MMBase:
http://www.mmbase.org/docs/
Connecting <application class="software">Apache</application>
and <application class="software">Tomcat</application>
using <systemitem class="library">mod_jk2</systemitem>
Since (for some odd reason) some network managers allow outgoing web
connections only to TCP port 80,
there might be people around that cannot access your
Tomcat
(and MMBase) server
through port 8080.
You can install a JK 2 mapping or a reverse proxy
in Apache,
so Tomcat
and MMBase
can be accessed through the
Apache web server
at port 80.
Apart from the port issue,
this has the advantage that you can use
Apache
to manage you SSL connections
and use your existing
Apache
logs and statistics facilities
for Tomcat
and MMBase as well.
Here we describe the installation and configuration of
the JK 2 Connector
connecting Apache
and Tomcat.
In this way,
Tomcat paths can be mapped
into Apache.
>From the
JK 2 Connector
website
(http://jakarta.apache.org/tomcat/tomcat-4.1-doc/config/jk2.html):
The JK 2 Connector
element represents
a Connector component that communicates
with a web connector via the AJP protocol.
This is used for cases where you wish
to invisibly integrate Tomcat 4
into an existing (or new)
Apache installation,
and you want Apache to handle
the static content contained in the web application,
and/or utilize Apache's
SSL processing.
In many application environments,
this will result in better overall performance
than running your applications
under Tomcat stand-alone
using the
HTTP/1.1 Connector.
However, the only way to know for sure
whether it will provide better performance for your application
is to try it both ways.