Please note: This page may still need some updates concerning OpenCms 7.

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.

1. Install the Java 2 SDK, version 1.4 or newer

Install the Java 2 SDK, version 1.4 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: This OpenCms 6 was tested with Java 1.4 and 1.5 only. Some features regarding file encoding where used that are not available with Java releases before 1.4.

Please note: FreeBSD users may need to setup new entropy sources in the O/S usingrndcontrol. 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

2. Install Tomcat

OpenCms 7.0 requires a Servlet 2.3 / JSP 1.2 standards compliant container. Tomcat 4 is the reference implementation of this Standard. This release was tested with Tomcat 4.1.x, Tomcat 5.0.x and Tomcat 5.5.x. Older versions of Tomcat (3.x and earlier) do not support this newer standard and are thus not usable for OpenCms 7.0. Tomcat 4.0.x was not tested, but may work.

Install Tomcat from http://jakarta.apache.org/tomcat/index.html 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://www.apache.org/httpd.html . 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. The reason for this is that OpenCms uses Swing classes for parsing RTF documents. Using these classes initializes the GUI system. This leads to an exception as the server process doesn't have access to the GUI system when not using the described argument.

3. Install MySQL

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 3.2, 4.0, 4.1 and 5.0. For performance reasons we recommend MySQL 5.0, or at last 4.1.

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=16M is recommended.

4. Deploy the opencms.war file

Copy 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.

5. Install OpenCms using the Setup-Wizard

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 with MySql, be sure that they exist before creating the database tables and importing the modules.

Important: Make sure you disable all popup blockers for the server URL you installed OpenCms on. Otherwise you will not be able to log in to the OpenCms Workplace.

6. Now your system is ready

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/

7. Security issues

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 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 privilege

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.