This page provides information on how to install OpenCms using Tomcat and MySQL. All installation parts are described as single steps. After completing each step you are strongly advised to verify the success of your work.
opencms.war file
Install the Java 2 SDK, version 5 or newer (from SUN
http://java.sun.com/products/j2se/). For details on how to install these components on your operating system, see the
documentation that comes with them. You must install the Java
SDK, not the
JRE (Java Runtime Environment) that is also available from SUN. The JRE is
not sufficient to run OpenCms!
Important: OpenCms 7.5.4 was tested with Java 5 (1.5) and 6 (1.6).
Please note: FreeBSD users may need to setup new entropy sources in the O/S using
rndcontrol. Otherwise the installation process may hang. For example, on a machine
with a network interface card on IRQs 9, you can execute
rndcontrol -s 9
OpenCms 7.5.4 requires a Servlet 2.4 / JSP 2.0 standards compliant container. Tomcat 6 is the reference implementation of this Standard. This release was tested with Tomcat 5.0.x, Tomcat 5.5.x and Tomcat 6.0.x. Older versions of Tomcat (4.x and earlier) do not support this newer standard and are thus not usable for OpenCms 7.5.4.
Install Tomcat from
http://tomcat.apache.org
into a folder of your choice. This is the
CATALINA_HOME folder. Don't forget to set the environment variables
CATALINA_HOME and
JAVA_HOME.
Test the installation by running Tomcat in standalone mode and check the examples. Note: Tomcat
uses port 8080 in standalone mode. If you wish, you can combine the servlet-engine with a webserver
like the Apache Web Server
http://httpd.apache.org.
Please see the documentation available with the webserver on how to combine it with your
servlet environment.
Please note: There's an extended OpenCms documentation module available from Alkacon Software GmbH on the opencms.org website that describes how to setup OpenCms with Apache httpd and Tomcat using mod_proxy.
Please note: On Linux systems, Tomcat's JVM has to be started with the command
line argument
-Djava.awt.headless=true.
Install MySQL from
http://www.mysql.com/downloads/index.html
(see the MySQL documentation on
http://www.mysql.com/documentation/index.html).
On Windows-based systems MySQL has to be installed on the
C:\ drive and should be registered as service using
%MYSQL_HOME%/bin/mysqld -install.
OpenCms can be used with MySQL 4.0, 4.1 and 5.0. For performance reasons we recommend MySQL 5.0.
Start the MySQL server by running the service (WIN32) or executing
%MYSQL_HOME%/bin/mysqld (UNIX).
Check that MySQL is running before you continue by starting the MySQL monitor (execute
mysql in your MySQL bin folder). The database works correctly if a MySQL prompt
appears after calling the monitor. Quit the MySQL monitor by typing exit and go to the next
step.
Important: You will have to increase the MySQL configuration variable
max_allowed_packet located in the MySQL configuration file (usually called
my.ini). For OpenCms, the limit should be as high as possible, a setting of
max_allowed_packet=32M is recommended.
opencms.war fileCopy the
opencms.war file from the binary distribution ZIP file to
CATALINA_HOME/webapps/. Replace
CATALINA_HOME with the real path to your Tomcat installation.
Start (or restart) Tomcat. Tomcat will now deploy the web application OpenCms.
Important: OpenCms requires that it's
*.war file is unpacked. OpenCms can not be deployed as war file only. Make sure Tomcat
does unpack the war file and creates the
CATALINA_HOME/webapps/opencms/ directory, placing the OpenCms files in this directory.
The default configuration for your Servlet containers / environment could be to not unpack the
deployed
*.war file. If this is so, you must unpack the opencms.war file manually. Use an unzip
tool for this,
*.war files are just
*.zip files with a different extension. The OpenCms setup wizard will display a
warning and not allow you to continue if you did not unpack the
*.war file.
Start the Setup-Wizard by pointing your webbrowser to
http://localhost:8080/opencms/setup/. Depending on your configuration, you have to
replace
localhost with your servername. The port 8080 is only used if you start Tomcat in
standalone mode.
Follow the instructions of the OpenCms Setup-Wizard. It will set up the OpenCms database and import all available modules into the system. For normal installations with MySql and Tomcat running on the same server, all default settings will fit your needs. If you are using different database users, be sure that they exist before creating the database tables and importing the modules.
Important: Make sure you disable all popup blockers and enable Javascript for the server URL you installed OpenCms on. Otherwise you will not be able to log in to the OpenCms Workplace.
Now your system is ready to use. You can login with username:
Admin and password:
admin. Please change this password as soon as possible. The login URL of OpenCms in a
default configuration is:
http://localhost:8080/opencms/opencms/system/login/.
Finally after you have installed OpenCms you should have a look at the security settings.
First change the
Admin user password of OpenCms by calling the user preferences (the "checkbox" icon in
the top menu on the main screen of the Workplace).
Then you can add a password to the MySQL database. Enter the following commands at the MySQL command line.
use mysql;
insert into user values ('localhost', 'opencmsuser', password('XXXXX'),\
'N','N','N','N','N','N','N','N','N','N','N','N','N','N');
insert into db values ('localhost', 'opencms', 'opencmsuser',\
'Y','Y','Y','Y','Y','Y','Y','Y','Y','Y');
flush privileges;
Make sure you replace
opencmsuser and
opencms with the name of your user and database in case you have changed them on the
setup wizard.
Don't forget to add the new user and password to all connect strings of the database in your
opencms.properties file. Only the new user can now connect to the OpenCms tables. For
more information see the MySQL documentation.
The OpenCms workplace users should be advised to use "strong" passwords to log in to the OpenCms workplace, at least with a minimum character count. OpenCms just checks if a password has a minimum length of 4 characters. See the next section for an alternative password validation method.
The "Admin" user password should be changed immediately after OpenCms was installed successfully.
It is possible to write a user defined password validation handler class to force the OpenCms users to enter a "strong" password matching the requested policies.
Therefore, the interface org.opencms.security.I_CmsPasswordHandler has to be implemented.
Usually, it is sufficient to extend the
class CmsDefaultPasswordHandler in the same package and overwrite the method
validatePassword(String password)
This handler class has to be configured in
the OpenCms configuration file WEB-INF/config/opencms-system.xml.
The class attribute value of the element <passwordhandler>
has to be set to the new password validation handler class.
<passwordhandler
class="com.example.CmsCustomPasswordHandlerfont>">
<encoding>UTF-8</encoding>
<digest-type>MD5</digest-type>
<param
name="compatibility.convert.digestencoding">false</param>
</passwordhandler>
The OpenCms workplace and its dialogs are programmed in a way that XSS attacks should not be possible.
This is not the case for HTML pages generated for the website using a template. The template programmer has to care for protection of the pages by using standard Java mechanisms (e.g. to use JSTL tags).
Example: no request parameter values should be printed out directly using the EL (element language), but they should be escaped using the JSTL (Java Standard TagLib). Of course the JSTL core tag library has to be defined in the head of the JSP:
<%@
taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core"%>
This is how to display the request parameter value "query" in a JSP:
Wrong: ${param.query}
Correct:
<c:out
value="${param.query}" /> or <c:out
value="${param.query}" escapeXml="true" /> (the <c:out>
tag escapes XML characters by default)
To avoid cross site scripting (XSS) the password auto completion should be disabled in OpenCms. For convenience reasons it is enabled per default setting. You can disable auto completion at the main login form (opencms/opencms/system/login) and at the change password form (/opencms/opencms/system/workplace/commons/preferences.jsp)
To prevent accessing cookies through Javascript, you could configure your application server to use the HttpOnly flag when setting cookies. Though still an IETF draft, the HttpOnly cookie is supported by most of the popular browsers. If in doubt, check http://www.browserscope.org/.
Alkacon Software recommends Tomcat 6.0 as an application server. OpenCms works "out of the box" with Tomcat 6.0 and has been tested with it. If you use another application server (JBoss, BEA, Websphere, Glassfish or other), please check if HttpOnly cookies are supported.
In Tomcat 6.0 the HttpOnly functionality can be enabled in conf/context.xml:
<Context useHttpOnly="true">
...
</Context>