Installation Troubleshooting
Not all installations go flawlessly. Here, I've tried to identify the most common installation problems and have explained how to fix them. Additionally, the OpenCms website—particularly the developers' mailing-list archives—is a good resource for troubleshooting information.
The most common sort of problem with OpenCms installations is that the character set of the Java VM and that of OpenCms do not match, which causes a number of different errors that all have messages that look something like this:
Java VM file encoding: Cp1252OpenCms encoding: ISO-8859-1
In almost every case, the solution is to make sure that the -Dfile.encoding=ISO-8859-1 flag is passed into the Java VM, either through the CATALINA_OPTS environment variable or by hardcoding the value into the catalina.sh (Linux/UNIX) or catalina.bat (Windows) files. If Tomcat is installed as a Windows Service, you will need to run the service uninstall/install routine I explained in the Windows Configuration section earlier.
It is also possible to change the OpenCms character set to match the system character set. To do this, edit the defaultContentEncoding property in the opencms.properties file under CATALINA_HOME/webapps/opencms/WEB-INF/config/, changing it to match the system character set (in the above example, it would be defaultContentEncoding=Cp1252). Be forewarned, though, that the system character set may not provide all of the necessary characters.
When configuring character sets, your best bets are the ISO-8859 sets and UTF-8.
On Linux installations of OpenCms 5.0, it is not uncommon to see a message as follows:
com.opencms.core.CmsException: 0 Unknown exception. Detailed error: Can not read projectId of tempfileproject for creating temporary file for editing! java.lang.NumberFormatException: null.
This error is caused by a bug in the installer that doesn't always set the appropriate value for the Temp File project ID. To fix this, edit the following file:
$CATALINA_HOME/webapps/opencms/WEB_INF/config/registry.xml
Change the element <tmpfileproject/> to <tmpfileproject>3</tmpfileproject>. Once you've saved the change, restart Tomcat.
Restarting Tomcat versus Reloading OpenCms
Tomcat includes an application for reloading individual servlets without restarting Tomcat. However, it is unclear whether all of the OpenCms classes (particularly the com.opencms.core.OpenCms singleton) are garbage collected. Many users have reported on the opencms-dev list that simply reloading the OpenCms servlet causes strange errors. So, it is always best to restart Tomcat rather than reload the individual servlet.
Importing Workplace Screen Freezes
As I noted in the Running the Install Wizard section, when installing with a Mozilla-based browser, the installation wizard will sometimes appear to hang during the importing of the workplace. This is due to a bug in the client-side JavaScript. The installation continues to run on the server. It is best to wait five minutes (ample time for the workplace installation to finish) and then reload the page using the browser's refresh button. You should then see a message that the import is complete.
This bug has been fixed in OpenCms 5.0.1, but still exists in earlier versions.
If you change the username or password for the MySQL database user that OpenCms uses, you will need to edit the following file:
$CATALINA_HOME/webapps/opencms/WEB-INF/config/opencms.properties
Change the value for the pool.mysql.user and pool.mysql.password variables. Restart Tomcat after saving your changes.
Finding More Installation Help
For more help on installation issues, try the OpenCms developers' mailing list and archives available at http://www.opencms.org/opencms/en/development/mailinglist.html.