Prerequisites
OpenCms will need a configured database and a functioning servlet engine. We will use MySQL for the database and Tomcat for the servlet engine. Since OpenCms uses the ISO 8859-1 character set, I will explain how to configure Tomcat to use that character set as default. Additionally, I will cover the registry settings that Windows installations require.
To install these packages on Linux, you will need to be root unless your system administrator has configured your system in a way that you can install these packages a different way (such as using sudo).
In Windows 2000, you will need to install the software as the Administrator user.
Configuring the MySQL Database
MySQL (http://www.mysql.com) is an open-source relational database server maintained by MySQL AB. While OpenCms supports other databases, including Oracle and MS SQL Server, MySQL runs on Windows and Linux, is free, and is the database on which OpenCms developers work.
OpenCms 5.0 can use either the 3.23.x or the 4.0.x version of MySQL. On Linux, if you are comfortable with MySQL, you may prefer to get the latest release from the MySQL website. However, if you are new to MySQL it is best to use the version your distribution contains (for example, at the time of this writing, Red Hat still used 3.23.x, while Gentoo used 4.0.x). That way, you can rely on your Linux vendor to provide updates and fixes.
On Windows, it is best to use the newest stable release from the MySQL website (at press time, 4.0.18 was the latest release).
MySQL on Linux
There are a couple of ways to install MySQL on a machine running Linux. You may decide to build the database from the source code, or you may download and install the binary provided by MySQL. Most Linux distributions provide a MySQL package (and often, it is installed already)—this is usually the best version to install.
Note
OpenCms does not require that the database be on the same machine as the servlet engine. OpenCms simply needs access to the database over the network (via JDBC).
To install the database, consult the documentation for your Linux distribution and that on the MySQL website http://www.mysql.com/documentation/index.html.
Many Linux distributions turn off network-based database connections by default, so you may need to manually enable the network-based server. Usually, this simply involves editing the /etc/my.cnf file. In the [mysqld] section, add the line port=3306. Consider the following relevant portion of my my.cnf file:
[mysqld]port=3306datadir=/var/lib/mysqlsocket=/var/lib/mysql/mysql.sock# The file continues on...
Make sure the database is running before proceeding. Most Linux systems provide init scripts for starting and stopping services. These scripts are usually located in /etc/init.d/. For instance, in Gentoo you can check to see if the database is up by running the command /etc/init.d/mysql status. If the server is not running, using the command start instead of status will start the server.
root # /etc/init.d/mysql status* Status: stoppedroot # /etc/init.d/mysql start* Starting mysql [OK]
Once the database is running, you are ready to move on to finishing the MySQL setup.
MySQL on Windows
While it is possible to build MySQL from source on Windows, it is much easier to download the Windows binary from the MySQL site and install it. Detailed documentation can be found at http://www.mysql.com/documentation/index.html.
Note
Windows users may find it helpful to download the MySQL documentation in CHM or HLP help-file formats. They can be added to the Windows help system.
Make sure that you install the MySQL server on your C: drive (the default location, C:\mysql, is fine). Register MySQL as a service by opening a command shell and running the following command:
shell> C:\mysql\bin\mysqld -install
Alternately, if the MySQL icon appears in your taskbar, you can right-click on it and choose the option to register the service. After that, you should be able to use the Windows Service utility to manage MySQL.
Before proceeding, start MySQL. You can start the service from the MySQL taskbar icon, or type NET START mysql at the command prompt.
Finishing the MySQL Setup
Once MySQL is running, set the 'root' password. This 'root' user has total control over the database, but is not necessarily correlated with the root or administrator accounts on the operating system.
>mysqladmin -u root password mypassword
Note
In Linux, mysqladmin is usually in the $PATH. In Windows, you may have to open a command shell and go to the C:\mysql\bin directory.
Next, connect using the mysql client:
>mysql -u root -p mysql
In the command above, -u root indicates that you are connecting to the database as the root (administrative) user. -p provides an interactive password prompt, and mysql at the end indicates the database that we will use (mysql is the name of the administration database for MySQL). Once you have connected to the database, it is time to create the opencms database and the user accounts that OpenCms will use to connect to that database.
The MySQL command for creating a database is CREATE DATABASE [dbname]. So the command to create a database named opencms is:
mysql> CREATE DATABASE opencms;
Make sure you include the semicolon at the end of the line. Now, create the opencms user:
mysql> GRANT ALL PRIVILEGES ON opencms.* TO opencms@localhost -> IDENTIFIED BY 'mypassword';
This statement gives permission to add, delete, and modify tables in the opencms database to the user opencms@localhost, whose password is mypassword. If OpenCms is to be run on a different machine than MySQL, you will need to create a similar statement to give log-on permission to opencms@<OpenCmsHostname> (where <OpenCmsHostname> is the host name or IP of the host running OpenCms).
The database is now prepared for OpenCms. It's now time to configure the servlet engine.
Configuring the Tomcat Servlet Engine
OpenCms is a Web-based application. It runs as a servlet inside a servlet container. Sun Microsystems, the company behind Java, has published the servlet standard, and since OpenCms adheres to the Java servlet 2.3 standard (http://jcp.org/en/jsr/detail?id=053), it will run in any servlet container that fully implements the standard.
Before you can run any Java applications, you will need to install the Java System Development Kit (JSDK). OpenCms 5.0 is written to take advantage of the features of JSDK 1.4, and will not run with earlier versions. Sun also packages a runtime-only version of Java called the Java Runtime Environment (JRE). OpenCms requires the JSDK, and will not run with just the JRE.
Note
Windows and Linux do not include the JSDK by default. If Java is not already installed, you can obtain Sun's version for free from http://java.sun.com/. At the time of writing this, neither IBM's JDK nor Blackdown's JSDK had reached the 1.4 specification, and so neither will run OpenCms.
For this book, I will use the Jakarta-Tomcat servlet engine (usually called simply Tomcat), which is jointly developed by the Apache Software Foundation (makers of the Apache Web Server) and Sun Microsystems. Like MySQL, Tomcat is open source and is the main platform that OpenCms developers use. Tomcat source and binaries are available from http://jakarta.apache.org. The binary releases are almost always suitable for use, but you may download and compile the source code if you prefer. While there are releases for version 5, which implement the new 2.4 servlet specification, OpenCms was developed according to the 2.3 servlet specification. Therefore, it's best to use a 4.1.x release of Tomcat (4.1.30 is the current stable release).
To install Tomcat on either Windows or Linux, simply unzip the archive into the desired directory and set the CATALINA_HOME environment variable to point to that directory. For Windows, there is a Tomcat release that uses a graphical installer. If you choose to install it this way, do not check the box that automatically configures Tomcat as a service. Later in this chapter, I will explain how to configure Tomcat as a Windows service.
Linux Configuration
In Linux, Tomcat is generally installed into /opt/tomcat or /usr/local/tomcat. Assuming the former location, set the CATALINA_HOME variable by running the following command:
export CATALINA_HOME=/opt/tomcat
Also, make sure that the JAVA_HOME environment variable is set. You can check by running env|grep JAVA_HOME or echo $JAVA_HOME. If either of these does not return the path to the JDK, you will need to set this environment variable to point to the location of your JDK installation.
To start Tomcat, run $CATALINA_HOME/bin/startup.sh and to stop it, run $CATALINA_HOME/bin/shutdown.sh. To streamline things a bit, I usually create a small wrapper script that looks something like this (named tomcat.sh):
#!/bin/bash
#############################################################
# Simple script to start and stop Tomcat.
# This script should be named tomcat.sh, and be executable
#############################################################
export CATALINA_HOME=/opt/tomcat
export CATALINA_OPTS='-Dfile.encoding=ISO-8859-1'
# Usually this is already set. If not, set it.
# export JAVA_HOME=/opt/sun-jdk-1.4.2.02
case "$1" in
start)
$CATALINA_HOME/bin/startup.sh
;;
stop)
$CATALINA_HOME/bin/shutdown.sh
;;
restart)
$CATALINA_HOME/bin/shutdown.sh
$CATALINA_HOME/bin/startup.sh
;;
*)
echo $"Usage: $0 {start|stop|restart}"
;;
esac
To start Tomcat with this script, you may just type ./tomcat.sh start, and to stop it, use ./tomcat.sh stop. This script will help you avoid one common mistake: it will keep you from accidentally typing shutdown (which shuts down Linux) instead of shutdown.sh (which shuts down Tomcat).
Windows Configuration
Whether you have installed with the graphical installer or by simply unzipping the archive into a directory, you will need to set two environment variables: CATALINA_HOME and JAVA_HOME. In Windows 2000, you can do this by right-clicking on My Computer and choosing Properties. Go to the Advanced tab. Select Environment variables and create two variables: CATALINA_HOME pointing to the Tomcat installation (e.g. C:\Program Files\Apache Group\Tomcat 4.1), and JAVA_HOME pointing to the J2SDK directory (e.g. C:\j2se1.4.2).
Because the Windows services do not use environment variables and OpenCms requires that extra options be passed into Tomcat, Tomcat must be installed from the command line rather than the graphical installer. Open up a command prompt, change the directory to Tomcat's bin directory with cd %CATALINA_HOME%\bin, and run the tomcat -install command as it is displayed below. Even though the following has been split for readability, it must be typed on just one line in order to run correctly:
>tomcat -install "Tomcat" %JAVA_HOME%\jre\bin\server\jvm.dll -Djava.class.path=%CATALINA_HOME%\bin\bootstrap.jar;%JAVA_HOME%\lib\t ools.jar -Dcatalina.home=%CATALINA_HOME% %CATALINA_OPTS% -Dfile.encoding=ISO-8859-1 -Xrs -start org.apache.catalina.startup.Bootstrap -params start -stop org.apache.catalina.startup.Bootstrap -params stop -out %CATALINA_HOME%\logs\stdout.log -err %CATALINA_HOME%\logs\stderr.log
After this has run, you should see a message saying something like:
The service was successfully installed.
If you ever need to uninstall the service, issue the tomcat -uninstall Tomcat command.
As with MySQL, Tomcat can be started and stopped either through the Windows Service utility or from the command line with NET START Tomcat and NET STOP Tomcat.
Note
Tomcat can act like a stand-alone web server. This is useful for development. Tomcat is sometimes used this way in production environments as well. However, Tomcat can also run cooperatively with another web server such as Apache or IIS.
Once Tomcat is installed, you may test it by opening your browser and typing in the server's IP address followed by port 8080 (for instance, http://10.0.1.13:8080). http://localhost:8080 will automatically resolve to your local host, and if you are browsing from the machine on which you are installing OpenCms, using this URL is easier. For the remainder of this book, I will use the localhost notation for URLs directed to OpenCms.
Some machines, whether Linux or Windows, may have firewalls or other security measures that block access to port 8080. Consult your firewall documentation for information on configuring it. Alternatively, you may instead choose to configure Tomcat to listen on the standard HTTP port, port 80. On a production server, you should make sure that the application is available on port 80—either by configuring Tomcat, or by setting it up to work cooperatively with another Web server. This will ensure that your site is available to all web surfers—even those behind restrictive firewalls.
Note
To configure Tomcat to listen on the standard HTTP port, make sure you are not running another web server already, and then edit the server.xml file (under $CATALINA_HOME/conf/ in Linux, %CATALINA_HOME%\conf\ in Windows). Find the Connector className=" org.apache.coyote.tomcat4.CoyoteConnector" element and change port="8080" to port="80". You will need to restart Tomcat before the change takes effect. Now, the URL no longer needs :8080 at the end.
There is one last step to configuring the environment before installing OpenCms. By default, OpenCms uses the ISO 8859-1 character set (sometimes referred to as the Latin-1 character set). To make sure that Tomcat uses this character set, you must pass it a special parameter: -Dfile.encoding=ISO-8859-1. In the Linux start script, I included a line that set this parameter as a value of CATALINA_OPTS. I also specified the parameter in the online command for adding Tomcat as a service on Windows. However, if you intend to start Tomcat with other tools, you can add the parameter to the catalina.sh (for Linux) or catalina.bat (for Windows).
OpenCms supports other character sets. Later in this chapter, I will cover configuring and using the UTF-8 character set, which supports multi-byte characters.
Note
The step of configuring character encoding is often overlooked, as it appears to be unimportant or unnecessary. However, not configuring encoding can result in strange, seemingly inexplicable errors.
After configuring encoding, restart Tomcat and make sure the default URL loads in your browser. Now that Tomcat and MySQL are configured, it's time to install the OpenCms Web ARchive (WAR) file.
One of the easiest, and most common, ways to increase the performance of a Java application is to adjust the memory settings for the JVM. In Sun's version of the java command, this can be done by setting the -Xmx and -Xms flags.
Use the CATALINA_OPTS environment variable (which we used for setting encoding) to set initial and max heap sizes. The example below sets the encoding to ISO-8859-1 (the default for OpenCms), and then sets the maximum amount of RAM allocated to Tomcat to be 512 MB, and the initial amount to 256 MB. These settings would work well on a system with 1 Gigabyte RAM, though you could certainly experiment with more aggressive settings.
CATALINA_OPTS="-Dfile.encoding=ISO-8859-1 -Xmx512M -Xms256M"
These options will control how much memory the JVM attempts to use. The higher you can set these, the better. Just remember that the database will need plenty of memory too. If the applications cause the system to start swapping to disk, performance will actually diminish. It may take some experimenting to find the right balance, but the improvements can be quite noticeable.