install.html

<html>
<head>
<title>OpenCms 8.0.3 installation</title>
</head>
<body>
<h1>OpenCms 8.0.3 installation</h1>
<p>This page provides information on how to install OpenCms using 
<a href="http://tomcat.apache.org" target="_blank" title="External link, opens in new window">Tomcat</a> and 
<a href="http://www.mysql.com" target="_blank" title="External link, opens in new window">MySQL</a>. All installation parts are described as
single steps. After completing each step you are strongly advised to verify the success of your
work.</p>

<ul>
<li>
<a href="#a1">Install the Java 2 SDK, version 5 or newer</a>
</li>
<li>
<a href="#a2">Install Tomcat</a>
</li>
<li>
<a href="#a3">Install MySQL</a>
</li>
<li>
<a href="#a4">Deploy the 
<code>opencms.war</code> file</a>
</li>
<li>
<a href="#a5">Install OpenCms using the Setup-Wizard</a>
</li>
<li>
<a href="#a6">Now your system is ready</a>
</li>
<li>
<a href="#a7">Security issues</a>
</li>
</ul>
<h2>
<a id="a1" name="a1"></a>Install the Java 2 SDK, version 1.5 or newer</h2>

<p>Install the Java JDK, version 5 or newer (from Oracle 
<code>
<a  href="http://www.oracle.com/technetwork/java/javase/downloads/index.html" target="_blank" 
title="External link, opens in new window">http://www.oracle.com/technetwork/java/javase/downloads/index.html</a></code>). For details on how to install these components on your operating system, see the
documentation that comes with them. You must install the Java 
<em>JDK</em> (Java Development Kit), not the 
<em>JRE</em> (Java Runtime Environment) that is also available from Oracle. The JRE is 
<em>not</em> sufficient to run OpenCms!</p>
<p>
<strong>Important</strong>: OpenCms 8.0.3 was tested with Java 5 (1.5) and 6 (1.6).</p>

<h2>
<a id="a2" name="a2"></a>Install Tomcat</h2>
<p>OpenCms 8.0.3 requires a Servlet 2.4 / JSP 2.0 standards compliant container. 
This release was tested with Tomcat 5.5.x, Tomcat 6.0.x. and Tomcat 7.0.x.</p>

<p>Install Tomcat from 
<code>
<a href="http://tomcat.apache.org"
target="_blank" title="External link, opens in new window">http://tomcat.apache.org</a>
</code> into a folder of your choice. This is the 
<code>CATALINA_HOME</code> folder. Don't forget to set the environment variables 
<code>CATALINA_HOME</code> and 
<code>JAVA_HOME</code>.</p>
<p>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 
<code>
<a href="http://httpd.apache.org" target="_blank" title="External link, 
opens in new window">http://httpd.apache.org</a></code>. 
Please see the documentation available with the webserver on how to combine it with your
servlet environment.</p>
<p>
<strong>Please note:</strong> 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.</p>
<p>
<strong>Please note:</strong> On Linux systems, Tomcat's JVM has to be started with the command
line argument 
<code>-Djava.awt.headless=true</code>.</p>
<h2>
<a id="a3" name="a3"></a>Install MySQL</h2>

<p>Install MySQL from 
<code>
<a href="http://www.mysql.com/downloads/index.html"
target="_blank" title="External link, opens in new window">http://www.mysql.com/downloads/index.html</a>
</code> (see the MySQL documentation on 
<code>
<a href="http://www.mysql.com/documentation/index.html"
target="_blank" title="External link, opens in new window">http://www.mysql.com/documentation/index.html</a></code>). 
On Windows-based systems MySQL has to be installed on the 
<code>C:\</code> drive and should be registered as service using 
<code>%MYSQL_HOME%/bin/mysqld -install</code>.</p>

<p>OpenCms can be used with MySQL 5.0, 5.1 and 5.5.</p>
<p>Start the MySQL server by running the service (WIN32) or executing 
<code>%MYSQL_HOME%/bin/mysqld</code> (UNIX).</p>
<p>Check that MySQL is running before you continue by starting the MySQL monitor (execute 
<code>mysql</code> 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.</p>
<p>
<strong>Important:</strong> You will have to increase the MySQL configuration variable 
<code>max_allowed_packet</code> located in the MySQL configuration file (usually called 

<code>my.ini</code>). For OpenCms, the limit should be as high as possible, a setting of at least 
<code>max_allowed_packet=16M</code> is recommended.</p>
<h2>
<a id="a4" name="a4"></a>Deploy the 
<code>opencms.war</code> file</h2>
<p>Copy the 
<code>opencms.war</code> file from the binary distribution ZIP file to 
<code>CATALINA_HOME/webapps/</code>. Replace 

<code>CATALINA_HOME</code> with the real path to your Tomcat installation.</p>
<p>Start (or restart) Tomcat. Tomcat will now deploy the web application OpenCms.</p>
<p>
<strong>Important</strong>: OpenCms requires that it's 
<code>*.war</code> file is unpacked. OpenCms can not be deployed as war file only. Make sure Tomcat
does unpack the war file and creates the 
<code>CATALINA_HOME/webapps/opencms/</code> directory, placing the OpenCms files in this directory.
The default configuration for your Servlet containers / environment could be to not unpack the
deployed 
<code>*.war</code> file. If this is so, you must unpack the opencms.war file manually. Use an unzip
tool for this, 

<code>*.war</code> files are just 
<code>*.zip</code> 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 
<code>*.war</code> file.</p>
<h2>
<a id="a5" name="a5"></a>Install OpenCms using the Setup-Wizard</h2>
<p>Start the Setup-Wizard by pointing your webbrowser to 
<code>http://localhost:8080/opencms/setup/</code>. Depending on your configuration, you have to
replace 
<code>localhost</code> with your servername. The port 8080 is only used if you start Tomcat in
standalone mode.</p>

<p>Follow the instructions of the OpenCms Setup-Wizard. It will set up the OpenCms database and
import all available&nbsp;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.</p>
<p>
<strong>Important:</strong> 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.</p>
<h2>
<a id="a6" name="a6"></a>Now your system is ready</h2>
<p>Now your system is ready to use. You can login with username: 
<code>Admin</code> and password: 
<code>admin</code>. Please change this password as soon as possible. The login URL of OpenCms in a
default configuration is: 

<code>http://localhost:8080/opencms/opencms/system/login/</code>.</p>
<h2>
<a id="a7" name="a7"></a>Security issues</h2>
<p>Finally after you have installed OpenCms you should have a look at the security settings.</p>
<p>First change the 
<code>Admin</code> user password of OpenCms by calling the user preferences (the "checkbox" icon in
the top menu on the main screen of the Workplace).</p>
<p>Then you can add a password to the MySQL database. Enter the following commands at the MySQL
command line.</p>
<blockquote>
<p>

<code>use mysql;
<br /> insert into user values ('localhost', 'opencmsuser', password('XXXXX'),\
<br /> &nbsp;&nbsp;&nbsp;'N','N','N','N','N','N','N','N','N','N','N','N','N','N');
<br /> insert into db values ('localhost', 'opencms', 'opencmsuser',\
<br /> &nbsp;&nbsp;&nbsp;'Y','Y','Y','Y','Y','Y','Y','Y','Y','Y');
<br /> flush privileges;</code>
</p>
</blockquote>
<p>Make sure you replace 
<code>opencmsuser</code> and 

<code>opencms</code> with the name of your user and database in case you have changed them on the
setup wizard.</p>
<p>Don't forget to add the new user and password to all connect strings of the database in your 
<code>opencms.properties</code> file. Only the new user can now connect to the OpenCms tables. For
more information see the MySQL documentation.</p></div>
</body>
</html>