Installing the OpenCms WAR File

As with most open-source projects, OpenCms is available in both source and binary releases. In Appendix A, I cover building OpenCms from source, but in this section, I will refer only to the binary build. Download the 5.0.1 release (opencms_5.0.1.zip) from http://www.opencms.org/opencms/en/download/index.html, the OpenCms downloads page.

OpenCms, like most Java servlets, is packaged in a WAR file. This file contains all the files necessary for running the application. In Tomcat, all WAR files go under the webapps/ directory (in $CATALINA_HOME/ on Linux and %CATALINA_HOME%\ on Windows).

Once you have downloaded the opencms_5.0.1.zip file, unzip it to a temporary directory and copy the opencms.war file into Tomcat's webapps directory. While Tomcat will eventually automatically detect the new WAR file, it is best to manually restart Tomcat, which will force it to reload all web applications. Note that OpenCms requires that the WAR be unpacked into a directory ($CATALINA_HOME/webapps/opencms). By default, Tomcat unpacks WARs automatically, but other servlet containers may require additional configuration to elicit this behavior.

Configuring OpenCms to Use UTF-8

UTF-8 (Unicode), which supports multi-byte character encoding, is also supported in OpenCms. To use UTF-8, you will have to change the -Dfile.encoding=ISO-8859-1, set earlier in the Configuring Encoding section, to -Dfile.encoding=UTF-8. If you are running Windows and have already installed Tomcat as a service, you will need to uninstall the service and rerun the install script with UTF-8 in place of ISO-8859-1.

Also, you will need to edit the OpenCms properties file to set the correct encoding. Stop Tomcat and edit the opencms.properties file under $CATALINA_HOME/webapps/ opencms/WEB_INF/. Find the line that reads:

defaultContentEncoding=ISO-8859-1

Change ISO-8859-1 to UTF-8 and save the file.

It is possible to use other character sets, but if you do so, you may also have to configure the encoding that your database uses. Consult your database documentation to find out.

Verify that Tomcat is using the correct character encoding (see the Configuring Encoding section), and then start Tomcat again.

Running the Install Wizard

Once the opencms.war file is in place and Tomcat is restarted, you are ready to run the installer.

Note

Regarding browsers, the OpenCms installation and workplace utilize advanced JavaScript. Because JavaScript implementations vary widely, OpenCms developers decided to target only the two most popular browser flavors: Internet Explorer and Mozilla (including Netscape and Firefox). Even between the two, there are some discrepancies in functionality. The OpenCms installation and workplace may or may not work with other browsers.

Open a browser and enter the following URL to the OpenCms installer:

http://localhost:8080/opencms/ocsetup
                                        

This will bring up the first screen of the OpenCms installation wizard. There are two installation modes: standard and advanced. Choosing the advanced mode will add three more screens of configurable details. Usually, the standard install is sufficient; however, for the sake of completeness, I'll go through the advanced setup.

Click on Continue to proceed to the database setup screen:

Set the User and Password fields for both Database Server Connection and OpenCms Connection to be the MySQL user created during MySQL setup. The rest of the fields should default to the correct values. Clicking on Continue will bring you to a page that warns that the existing opencms database will be dropped. Allowing the database to be dropped is fine as it contains nothing.

If everything on this screen says Ok, hit Continue. Failures during database installation usually indicate that the permissions for the MySQL user opencms were not set correctly. You can log in to the database and check the user by running a SELECT against the mysql.user table. Review the GRANT statements in the Finishing MySQL Setup section, and make sure that the user has the appropriate permissions.

The version-checking screen that follows will verify that all of the components are recognized. Since we are using the well-tested JDK 1.4/Tomcat/MySQL platform, things should check out here:

From this point, there are a few configuration screens that will show up only for the advanced setup mode. They provide an opportunity to tune parameters for caching, logging, and running. The first time you run the configuration, be cautious with changes to the advanced screens.

All of the parameters in these screens are written to the opencms.properties and registry.xml files, both of which are in $CATALINA_HOME/webapps/opencms/WEB-INF/config/. They can be changed after installation.

Advanced Setup Screens

If you are not running the advanced setup, which includes many options for configuring details of the system, you may prefer to skip to the Basic Setup Screens section.

Here is the first advanced screen:

Of note here is the database configuration section. If you are strapped for resources, lowering the minimum and maximum connections can boost performance. Also, if you are on a slow or overloaded machine, upping the timeout is a good idea. Usually, the defaults work fine.

Here are the details of the fields:

• Min. Conn. and Max. Conn.: Control the minimum and maximum number of connections that OpenCms makes to the database. When the servlet is started, it will establish the minimum number of connections specified here.
• Increase Rate : Determines how many new connections will be created at a time. The default, 5, specifies that when all open connections are exhausted, five new ones will be created unless the maximum limit is reached. Requests will then wait for an open connection.
• Timeout :Determines how long OpenCms will wait for a connection to return results before it gives an error.
• Max. Age :Determines how long a connection will live before it is cleaned up.
• Session Failover :Determines whether or not OpenCms will attempt to reuse session data on a different connection if the first connection fails.
• Backup Published Resources : Determines whether or not backup copies are made of each document when it is published. You should always leave this enabled.
• Http Streaming : Determines whether the servlet should buffer data before sending it to the client. This is covered in greater detail in Chapter 8. Enable this for now.
• The Cache Parameters section: Contains settings for the OpenCms caches. The first ten entries merely specify the maximum number of entries for each data type.
• Element Cache : Used to cache XML Templates. It should remain enabled.
• Cache URI , Cache Elements , and Cache Variants : Used by the FlexCache to determine how it caches JSPs and other resources. This is discussed in Chapters 4 and 8. The default is sufficient for most cases.

OpenCms can statically export all of the documents in the repository, a feature that we will later cover in detail. By default, OpenCms is configured to export all pages. This is not always desirable. For this reason, I disable that behavior during setup. These default values are otherwise good for now.

Each of the properties in the preceding screenshot will be discussed in detail in Chapter 8. As I said previously, it is possible to make the same change at any time by editing the $CATALINA_HOME/webapps/opencms/WEB-INF/config/opencms.properties file.

Logging can be a big performance killer on a production machine, but a lifesaver during development. To allow for optimum flexibility, OpenCms has a robust logging system. The defaults are sufficient for our needs. On a production server, consider turning off the *_info channels. The fields depicted in the screenshot are:

• OpenCms Logging determines whether logging will be used at all.
• If Timestamp is enabled, each log will be marked with date and time info.
• If Memory is enabled, each log entry will include information on memory use. This is useful in debugging problems with memory consumption.
• Date Format allows you to specify an alternative date format.
• Log Queue Max Age and Log Queue Max Size allow you to specify time and memory size constraints for log queuing and flushing.
• Log File identifies the location and name of the file to which log information will be written.
• Logging Channel Name determines whether the logger will determine how to log information based on log channels. If enabled, the logger will analyze the channel of every log message and determine whether the message should be logged.
• The thirteen radio boxes identify the available logging channels for OpenCms. If enabled, the logger will write messages for that channel to the log file. If disabled, log messages for that channel will be silently discarded.

The final advanced configuration screen allows configuration of some miscellaneous details:

There is one slightly misleading parameter here. The final setting, Maximum allowed upload file size , is only the maximum file size OpenCms will attempt to store in the database. MySQL has a maximum file size, too, and it is only 2 MB by default.

• The first three parameters are for FlexCache, described in detail in Chapters 4 and 8. Flex Cache [so spelled here] should be enabled.
• The second parameter, Cache Offline , determines whether the offline project is cached.
• Force GC determines whether the Java garbage collector will be explicitly called on the FlexCache. After the cached objects are deleted from FlexCache, OpenCms will request that the VM run the garbage collector to delete those objects.
• The Filename translation and Directory Translation are used to determine how to handle file and folder names from previous versions of OpenCms. To be on the safe side, you should leave these enabled.
• The five FlexCache parameters, discussed in Chapters 4 and 8, determine how much space is given to the cache as a whole, and to the individual entries and variants in the cache.
• Directory Index File(s) determines what files OpenCms will try to find and use if a directory (rather than a file) is requested.
• The MAC Address field can be used to specify the MAC address of the system's NIC card. OpenCms will automatically determine this unless you set it here. Since MAC addresses are unique, OpenCms uses them to generate unique IDs.
• Finally, File Size determines the upper size limit on uploaded files.

This completes the advanced configuration; we now return to the regular setup screens.

Basic Setup Screens

On this screen, you are given the opportunity to import the workplace, as shown in the following screenshot. The workplace is the suite of content-management tools—something you definitely want.

Click Yes and continue.

Note

On the standard installation, there is a second question on this screen: Do you want to use directory translation? Answering Yes ensures compatibility with old OpenCms databases and modules, but doesn't affect performance adversely.

The following screen loads the workplace:

2118 individual steps are performed during this phase of the install, and it will take around five minutes to complete. Once it is done, the Continue, Back, and Cancel buttons will become active. Scroll around in the information box to make sure there aren't any errors. If things look good, continue.

The following screenshot explains the details of the WYSIWYG editor, which requires ActiveX (and thus IE) to function correctly. It also explains that there is an advanced sourcecode editor available. Read the message and then check the box.

The setup is now complete. Congratulations! Clicking on the here link in the screenshot that follows loads the OpenCms workplace, which we'll discuss in the next chapter.

Note

If the installation fails for some reason and you have to re-run the wizard, you will need to edit the $CATALINA_HOME/webapps/opencms/WEB-INF/config/ opencms.properties file and change the value of the wizard.enabled property to true. This unlocks the installation wizard. Otherwise, this property should always be set to false.

Manually Configuring Settings

OpenCms uses two configuration files, both of which are located in $CATALINA_HOME/webapps/opencms/WEB-INF/config/. The first file is called opencms.properties. It conforms to the Java standard for properties files. As a general rule of thumb, the directives in this file have to do with the core operations of the server, though there are a few parameters in this file that do not necessarily meet that criterion. The second file, registry.xml , is an XML file containing directives for the structure and operation of the content management system.

While OpenCms should function fine without any modifications to either of these files, there are a few changes to each file that are worth making at this time.

By default, when resources are published, OpenCms attempts to convert most of them (excluding JSP files) to static HTML files. This is called static export. While statically exporting documents enables them to be served faster, it also means that most dynamic elements will be replaced with static representations. Static exports can be very useful for large sites, high traffic, or underpowered servers, but to take full advantage of the dynamic nature of OpenCms, static export needs to be turned off. See Chapter 8 for a more thorough discussion of exporting.

Note

Static export only affects published resources. One of the greatest sources of confusion for the new user is that dynamic pages will function correctly in the offline project, but when they are published, they are no longer evaluated dynamically. In some cases, the result is that a static rendering of a dynamic page will be returned. In other cases, the user will just receive an error or a string of question marks (?????). Turning static export off fixes this problem.

If you followed the instructions in the advanced setup, you should have already turned off static exports. Otherwise, you will need to do so manually.

To turn off static export, open the opencms.properties file in a text editor. Find the staticexport.enabled property (it is about halfway through the file) and set it to true. This means that resources that are specifically tagged for static export (such as images) can still be exported. The next property after this should be staticexport.default.export . Set that to dynamic.

This setting will make sure that unless explicitly marked otherwise, files will be treated as dynamic, and not exported to static HTML. In Chapter 8, Deploying an OpenCms Solution, we will revisit the exporting issue in more detail.

Now open the registry.xml file. In order to take advantage of e-mail notifications in the workplace, you will need to configure a few parameters in this file. Set <smtpserver/> and <smtpserver2/> to point to your own mail servers. On Linux and UNIX machines that run sendmail, this value can usually be set to localhost. <defaultmailsender/>, <mailto/>, and <mailfrom/> all need to be set to valid e-mail addresses. In particular, <mailto/> should be set to the OpenCms administrator (which is probably you).

The relevant section should look something like this:

                                <smtpserver>localhost</smtpserver>
                                <smtpserver2>mail.mydomain.com</smtpserver>
                                <defaultmailsender>opencms@mydomain.com</defaultmailsender>
                                <checklink>       
                                <mailfrom>opencms@mydomain.com</mailfrom>   
                                <mailto>me@mydomain.com
                                </mailto>
                                </checklink>

Also, if you are running a Linux server, you need to replace <tempfileproject/> with <tempfileproject>3</tempfileproject>—a bug in the installer fails to set this correctly.

Once you have completed this configuration, manually restart Tomcat to effect the new changes.