OpenCms
From InstallationWiki
| Official Page |
| Project Documentation |
| Download |
|
OpenCms from Alkacon Software is a professional, easy to use website content management system. OpenCms helps content managers worldwide to create and maintain beautiful websites fast and efficiently.
The fully browser based user interface features configurable editors for structured content with well defined fields. Alternatively, content can be created using an integrated WYSIWYG editor similar to well known office applications. A sophisticated template engine enforces a site-wide corporate layout and W3C standard compliance for all content.
OpenCms is based on Java and XML technology. It can be deployed in an open source environment (e.g. Linux, Apache, Tomcat, MySQL) as well as on commercial components (e.g. Windows NT, IIS, BEA Weblogic, Oracle).
As open source software, OpenCms is free of licensing costs.
This article walks through the process of installing and configuring OpenCms. We will focus on the two most common platforms, Linux/MySQL/Tomcat and Windows/MySQL/Tomcat. Installation on other platforms is similar enough for these instructions to suffice.
Contents |
[edit] Prerequisites
OpenCms will need a configured relational database and a functioning servlet engine. We will use MySQL for the database and Tomcat for the servlet engine. In this section, we will look at the process of installing and configuring these two servers.
To install these packages on Linux, you will need to be logged on as the root user unless your system administrator has configured the system so that you can install these packages in a different way (such as using sudo).
In Windows, you will need to install the software as the Administrator user. You will need to be running at least Windows 2000. (Later versions will work, too.)
[edit] Configuring the MySQL Database
MySQL (http://www.mysql.com) is an open-source relational database server maintained by MySQL AB. While OpenCms supports other databases, including Oracle and PostgreSQL, there are three distinct advantages to using MySQL:
MySQL runs on Windows and Linux.
- It is Open Source and free of charge.
- It is the database on which OpenCms developers work.
OpenCms 6.2 can use versions of MySQL from 3.2 to 5.0. If you are using Linux, you may prefer to get the latest release from the MySQL website, but most Linux versions come with some version of MySQL, and if you are new to MySQL it is best to use that version. That way, you can rely on your Linux vendor to provide updates and fixes. If you are using Windows, it is best to use the newest stable release from the MySQL website.
| OpenCms has been officially tested on the following databases: MySQL versions 3.2.x-5.0.x, Oracle8i, 9, and 10, and PostgreSQL 7.4 and 8.0. PostgreSQL support is new in version 6 of OpenCms. Experimental support for MS SQL Server has been added in 6.2. ANSI SQL-92 compliant database servers should work as well. |
[edit] MySQL on Linux
There are two ways to install MySQL on a machine running Linux. You can build the database from the source code, or you can download and install the binary code provided by MySQL. Most Linux distributions provide a MySQL package (which is often installed already), and this is usually the best version to install.
| OpenCms does not require the database to be on the same machine as the servlet engine. It simply needs access to the database over the network (via JDBC). |
To install the database, consult the documentation for your Linux distribution and the documentation on the MySQL website, http://www.mysql.com/documentation/ index.html.
In many Linux distributions network-based database connections are turned off by default, so you may need to enable the network-based server. This usually involves adding the line port=3306 in the [mysqld] section of the /etc/my.cnf file. For example, here is the relevant portion of my my.cnf file:
[mysqld] port=3306 datadir=/var/lib/mysql socket=/var/lib/mysql/mysql.sock # The file continues on...
The text in bold tells MySQL to listen on the network port 3306 of your server. OpenCms will connect to this port in order to communicate with the database.
You may also want to ensure that the skip-networking parameter is not set anywhere in the my.cnf configuration file, as that will disable network startup. (Debian-based Linux distributions set this parameter by default.)
Make sure the database is running before proceeding. Most Linux systems provide initialization scripts for starting and stopping services. These scripts are usually located in /etc/init.d/. For example, in Gentoo Linux you can check to see if the database is up with the command /etc/init.d/mysql status. If the server is not running, using this command with start instead of status will start the server:
root # /etc/init.d/mysql status * Status: stopped root # /etc/init.d/mysql start * Starting mysql [OK]
Once the database is running, you are ready to move on to finishing the MySQL setup.
[edit] MySQL on Windows
Although it is possible to build MySQL from source code on Windows, it is much easier to download the binary code from the MySQL site. Detailed documentation can be found at http://dev.mysql.com/doc/.
| Windows users may find it helpful to download the MySQL documentation in CHM or HLP help-file formats. It can then be added to the Windows help system. |
Make sure that you install the MySQL server on your C: drive (the default location, C:\mysql, is fine). Register MySQL as a service by opening a command shell and running the following command:
shell> C:\mysql\bin\mysqld install
Alternatively, if the MySQL icon appears in your system tray, you can right-click on it and choose the option to register the service. After that, you should be able to use the Windows Service utility to manage MySQL.
Before proceeding, start MySQL. You can start the service from the MySQL system tray icon, or by using the Services utility in the Windows Control Panel.
[edit] Finishing the MySQL Setup
OpenCms occasionally needs to import large files (primarily in the form of OpenCms modules) into the database. By default, MySQL does not allow large files to be inserted into the database. This is a security measure, and it makes sense in many contexts. But in this case we will need to allow MySQL to insert larger files. To do this, you will need to edit MySQL's configuration file (in C:\mysql\my.ini in Windows and /etc/mysql/
my.cnf or /etc/my.cnf in Linux). Set max_allowed_packet to allow files as large as 16 megabytes:
max_allowed_packet = 16M
Save the file and restart MySQL so that the changes take effect. (In Windows you can do this from the MySQL icon in the system tray. In Linux, you can do this from the init script: /etc/init.d/mysqld restart.)
Once MySQL is running again, set the password for the MySQL user named root. This root user has total control over the database. (The MySQL root user is not the same as the operating system's root user and can have a different password.)
>mysqladmin -u root password mypassword
In Linux, mysqladmin is usually in the $PATH. In Windows, you may have to open a command shell and go to the C:\mysql\bin directory.
|
Next, connect using the mysql client:
>mysql -u root -p mysql
In the command above -u root indicates that you are connecting to the database as the root (administrative) user. You should only connect as root for administrative tasks (as we are about to do now). -p provides an interactive password prompt, and mysql at the end indicates the name of the database that we will use.
A database server such as MySQL or Oracle can have many different databases, where each database is allocated to store some particular set of information. OpenCms will use its own database (which we will name opencms) to store its data. MySQL has its own database, named mysql, which contains information that MySQL uses to manage the other databases.
|
The mysql database is used for storing information about permissions. MySQL uses this information to determine who has access to which databases. Once you have connected to the database, it is time to create the opencms database and add the user accounts that OpenCms will use to connect to that database.
The MySQL command for creating a database is CREATE DATABASE [dbname], so the command to create a database named opencms is:
mysql> CREATE DATABASE opencms;
The semicolon at the end of the line indicates that the command is complete. (Without it you would get the prompt ->, which indicates that the SQL interpreter expects you to add more to the command. If this happens, you can just type ; to indicate that the command is complete.) To make sure that the database has been successfully created, you can enter the SHOW DATABASES command:
mysql> SHOW DATABASES; +----------+ | Database | +----------+ | mysql | | opencms | | test | +----------+ 3 rows in set (0.00 sec)
Next we now need to create a user to access this database. We will call this user opencms:
mysql> GRANT ALL PRIVILEGES ON opencms.* TO opencms@localhost IDENTIFIED BY 'mypassword';
This statement gives permission to add, delete, and modify (ALL PRIVILEGES) all tables (opencms.*) in the opencms database to the user opencms@localhost, whose password is mypassword. If OpenCms is to be run on a different machine from MySQL, you will need to create a similar statement to give log-on permission to opencms@<OpenCmsHostname> (where <OpenCmsHostname> is the host name or IP of the host running OpenCms).
Increasingly, Linux distributions are using the default domain localhost.localdomain instead of simply localhost. If this is the case with your Linux distribution, you will need to alter the example above to grant permissions to opencms@localhost.localdomain.
|
To disconnect from the database and exit, type the quit command at the mysql prompt and you will be returned to the operating system shell:
mysql> quit Bye $
The database is now prepared for OpenCms. It's now time to configure the servlet engine.
[edit] Configuring the Tomcat Servlet Engine
OpenCms is a web-based application. It runs as a servlet inside a servlet container. Sun Microsystems, the company behind Java, has published the servlet standard, and since OpenCms adheres to the Java servlet 2.3 standard (http://jcp.org/en/jsr/ detail?id=053), it will run in any servlet container that fully implements this standard.
Before you can run any Java applications, you will need to install the Java' System' Development' Kit ('JSDK). OpenCms 6.2 is written to work with JSDK 1.4 and 1.5, it and will not run with earlier versions. Sun also packages a runtime-only version of Java called the Java' Runtime' Environment (JRE). OpenCms requires the JSDK, and will' not' run' with' just' the' JRE.
| By default, Windows and Linux do not include the Sun JSDK. If Java is not already installed, you can obtain Sun's version for free from http://java.sun.com/. At the time of writing, neither IBM's JDK nor Blackdown's JSDK has been thoroughly tested with OpenCms. |
For this tutorial, we will use the Jakarta-Tomcat servlet engine (usually called simply Tomcat), which is jointly developed by the Apache Software Foundation (makers of the Apache web server) and Sun Microsystems. Like MySQL, Tomcat is open source and is the main platform used by OpenCms developers. Tomcat source files and binary files are available from http://jakarta.apache.org/site/downloads/downloads_tomcat.html. The binary releases are almost always suitable for use, but you may download and compile the source code if you prefer. Although OpenCms can run on the older 4.1 version of Tomcat, we will use the newer (and very stable) 5.0 version. To install Tomcat on either Windows or Linux, unzip the archive into the desired directory and set the CATALINA_HOME environment variable to point to that directory. For Windows, there is a Tomcat release that uses a graphical installer.
[edit] Linux Configuration
In Linux, Tomcat is generally installed into /opt/tomcat or /usr/local/tomcat. Any user on the system can run Tomcat as long as they have permission to read, write, and execute files in the tomcat directory.
Assuming that Tomcat is in /opt/tomcat, set the CATALINA_HOME variable by running the following command (you may want to put it in your .bash_profile file.):
export CATALINA_HOME=/opt/tomcat
Also, make sure that the JAVA_HOME environment variable is set. You can check this by running env|grep JAVA_HOME or echo $JAVA_HOME. If either of these does not return the path to the JDK, you will need to set this environment variable to point to the location of your JDK installation.
To start Tomcat, run $CATALINA_HOME/bin/startup.sh and to stop it, run $CATALINA_ HOME/ bin/shutdown.sh. To streamline things a bit, I usually create a small wrapper script that looks something like this (named tomcat.sh):
#!/bin/bash
#############################################################
# Simple script to start and stop Tomcat.
# This script should be named tomcat.sh, and be executable
#############################################################
export CATALINA_HOME=/opt/tomcat
# Usually this is already set. If not, set it.
# export JAVA_HOME=/opt/sun-jdk-1.4.2.11
case "$1" in
start)
$CATALINA_HOME/bin/startup.sh
;;
stop)
$CATALINA_HOME/bin/shutdown.sh
;;
restart)
$CATALINA_HOME/bin/shutdown.sh
$CATALINA_HOME/bin/startup.sh
;;
*)
echo $"Usage: $0 {start|stop|restart}"
;;
esac
To start Tomcat with this script, you may just type ./tomcat.sh start, and to stop it, type ./tomcat.sh stop. This script will help you avoid one common mistake it will keep you from accidentally typing shutdown (which shuts down Linux) instead of shutdown.sh (which shuts down Tomcat).
[edit] Windows Configuration
Once you have installed Tomcat, you will need to make sure that the Windows environment variables CATALINA_HOME and JAVA_HOME have been set.
To check this, right-click on My Computer and choose Properties. Go to the Advanced tab, select Environment variables, and make sure that CATALINA_HOME and JAVA_HOME are defined. If not, you will need to create these two variables. CATALINA_HOME should point to the Tomcat installation (e.g. C:\Program Files\Apache Group\Tomcat 5.0), and JAVA_HOME should point to the J2SDK directory (e.g. C:\j2se1.4.2).
Tomcat can be started and stopped either through the Service utility in the Windows Control Panel or by clicking on the Tomcat icon in the system tray.
| Tomcat can act like a stand-alone web server. This is useful for development. Tomcat is sometimes used this way in production environments as well. However, Tomcat can also run cooperatively with another web server such as Apache or MS IIS. |
[edit] Check Your Configuration
Once Tomcat is installed, you may test it by opening your browser and typing in the server's IP address followed by port 8080 (for instance, http://10.0.1.13:8080). http:// localhost:8080 will automatically resolve to your local host, and if you are browsing from the machine on which you are installing OpenCms (that is, if you are running the web browser and Tomcat on the same machine), using this URL is easier. For the remainder of this book, we will use the localhost notation for URLs directed to OpenCms.
Some machines, whether Linux or Windows, may have firewalls or other security measures that block access to port 8080. Consult your firewall documentation for information on configuring it.
You may choose to configure Tomcat to listen on the standard HTTP port, port 80. On a production server, you should make sure that the application is available on port 80 either by configuring Tomcat, or by setting it up to work cooperatively with another web server. This will ensure that your site is available to all web surfers even those behind restrictive firewalls.
| The OpenCms server contains documentation on configuring Tomcat to work in cooperation with Apache. This is the most common configuration for production‑level servers. For testing and development, though, using Tomcat on port 8080 is the most convenient. |
In previous releases of OpenCms, Tomcat had to be explicitly configured to use the ISO 8859-1 character set. This is no longer required.
[edit] Tuning the JVM
One of the easiest, and most common, ways to increase the performance of a Java application is to adjust the memory settings for the JVM. In Sun's version of the java command, this can be done by setting the -Xmx and -Xms flags.
Use the CATALINA_OPTS environment variable to set initial and maximum heap sizes. The example below sets the maximum amount of RAM allocated to Tomcat to be 512 MB, and the initial amount to 256 MB. These settings would work well on a system with one gigabyte of RAM, but you could certainly experiment with more aggressive settings.
CATALINA_OPTS=" -Xmx512M -Xms256M"
These options will control how much memory the JVM attempts to use. The higher you can set these, the better. Just remember that the database will need plenty of memory too. If the applications cause the system to start swapping to disk, performance will actually diminish. It may take some experimenting to find the right balance, but the improvements gained with carefully tuned JVM memory usage can be quite noticeable.
[edit] Installing the OpenCms WAR File
As with most open-source projects, OpenCms is available in both source and binary releases. We will use the binary version. Download the 6.2 release (opencms_6.2.0.zip) from the OpenCms downloads page:
http://www.opencms.org/opencms/en/download/index.html
OpenCms, like most Java servlets, is packaged in a WAR ('Web 'ARchive) file. A WAR file is a special kind of JAR file (which, in turn, is a special kind of ZIP file) that contains all the files necessary for running a Java servlet-based application. You can view the contents with standard JAR or ZIP tools. For example, to get a list of files in the archive, run jar -tf at a command line. In Tomcat, all WAR files are in the webapps/ directory (in $CATALINA_HOME/ on Linux and %CATALINA_HOME%\ on Windows).
Once you have downloaded the opencms_6.2.0.zip file, unzip it to a temporary directory and copy the opencms.war file into Tomcat's webapps/ directory. While Tomcat will eventually detect the new WAR file automatically, 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 its own directory ($CATALINA_HOME/webapps/ opencms). By default, Tomcat automatically unpacks a WAR into its own directory, but other servlet containers may require additional configuration to elicit this behavior.
Initially, the opencms/ directory and the opencms.war file will contain the same information. But over time, OpenCms will write new files into the $CATALINA_HOME/webapps/opencms directory. These files will not be present in the opencms.war file. When running backups, make sure that you copy the directory, not the WAR file. Otherwise, you will lose critical data. (In fact, once the opencms/ directory has been unpacked, you can safely delete opencms.war.)
|
[edit] Running the Install Wizard
Once the opencms.war file is in place and Tomcat is restarted, you are ready to run the installer. The installer is web-based. In order to successfully use it, you will need to make sure of two things. First, JavaScript must be enabled. Second, your browser must allow popups from the appropriate domain (localhost, in our case).
| 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 work with other browsers, but it has not been thoroughly tested. |
Open a browser and enter the following URL to the OpenCms installer:
http://localhost:8080/opencms/setup
This will bring up the first screen of the OpenCms installation wizard. This first screen displays information about the license under which OpenCms is made available the GNU Lesser General Public License. The full text of the license is available in the license.txt file that is included in the opencms-6.2.0.zip file. It is also available online at the GNU website:
http://www.gnu.org/licenses/licenses.html#LGPL.
If you are not familiar with the terms of this license, you should read about it at the GNU website, as it may have some ramifications on how you develop in OpenCms.
On the first screen of the installer, you will be asked to accept the terms of the license:
You must agree to the license and select yes before the Continue button will become active.
Once you have agreed to the license, OpenCms will perform a quick test to determine whether your system already has the necessary components.
During the system check, the OpenCms installer is looking for certain key components that it requires:
- A modern JDK
- A known operating system
- A known servlet engine
- A DOM-compliant XML parser
- An unzipped version of the WAR file (See the section above entitled "Installing the OpenCms WAR File")
If you have the necessary components, the continue button at the bottom will be active, but if something is not installed correctly, you will not be allowed to continue. In such a case, OpenCms will indicate which components are not installed or are mis-configured.
Once your system has passed the system test, database installation will begin. OpenCms will create over thirty tables inside the database we set aside for it.
The first field on the screen, Select Database, allows you to choose the type of database OpenCms will use. Out of the box, OpenCms supports multiple versions of MySQL, Oracle, and PostgreSQL, as well as databases that are ANSI SQL-92 compliant. In 6.2, experimental MS SQL Server support has also been added. Choose the appropriate version of MySQL. The screen will refresh, and you may then complete the Database specific settings section of the screen.
In the section entitled Finishing the MySQL Setup we set up a MySQL user called opencms. We granted this user all privileges in the OpenCms database. Enter this username and password into both the Setup Connection and the OpenCms Connection sets of fields.
For the most secure configuration, you may choose to restrict the opencms user to only specific database operations, such as INSERT, DELETE, and SELECT. While this does increase security, it may also prevent certain modules from installing or functioning correctly. Production systems will benefit from a more secured user, but such restrictions may slow development on pre-production servers. If you use a restricted opencms user, you will need to use some more privileged user to run the installation. Fill in the Setup Connection field with the privileged user, and OpenCms Connection with the less-privileged opencms user.
|
Both the Connection String and Database fields should be set correctly already. However, if you have a non-standard installation or if your database runs on a different server than the one on which Tomcat runs, you may need to change this for OpenCms to connect to the correct database.
At the bottom of the Database specific settings section of the form is a checkbox labeled Create database and tables. We have already created the database, but we have not created the tables. You will need to leave this checked. Click on Continue, and you will see a warning indicating that the opencms database already exists.
This warning prompts you to drop the database. The opencms database that we created earlier has no data in it, so we can choose Yes. (Clicking No will simply return you to the previous screen.) If your database settings were correct and the users in the Setup Connection and the OpenCms Connection fields have correct permissions, you should get a message saying that the database was successfully dropped, then created, and that the tables were all created successfully.
Click Continue to go on to the module selection screen.
OpenCms uses a module framework for extending functionality. At the core of OpenCms are the basic content management and service capabilities, but most other functionality is contained in add-on packages called modules. On the module selection screen, you will have a chance to choose which of the built-in modules you would like automatically installed with OpenCms.
There are over fifty modules on the Module selection screen all of which are selected by default. A few of them provide crucial functions to OpenCms. Some just provide tutorials, example code, how-to documents, and manuals. For the first install, it is best to leave everything selected. On a production system, you may want to uncheck the Alkacon Documentation modules and the TemplateOne demo modules.
A word of warning': Do not deselect a module unless you know what it does. Some modules provide tools that are necessary for a fully functional OpenCms installation.
Click Continue to go on to the Settings screen.
On this screen, you will be prompted to enter or verify some basic information about OpenCms. For the first field, you are instructed to Enter your server s ethernet (MAC) address. A MAC ('Media Access 'Control) address is an identifier assigned to Ethernet hardware by the manufacturer of the Ethernet card. Every Ethernet card has its own unique identifier. OpenCms uses this address to generate system-specific (and unique) identifiers (UUIDs Universally Unique Identifiers). While it is easy for you to get your MAC address, the Java security model prevents Java applications from accessing that information, so you have to enter this information manually.
[edit] Finding your MAC Address on Linux
To find your MAC address on Linux, you can use the command-line program ifconfig to give you information about the configuration of your Ethernet interfaces. Most of the time, you will want information about the first Ethernet card on your system, so you will use the following command:
$ ifconfig eth0 eth0 Link encap:Ethernet HWaddr 4F:A1:F1:C2:36:BF inet addr:10.12.7.14 Bcast:10.12.7.255 Mask:255.255.255.0 UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 RX packets:8871 errors:0 dropped:0 overruns:0 frame:0 TX packets:1359 errors:0 dropped:0 overruns:0 carrier:1 collisions:0 txqueuelen:1000 RX bytes:1575038 (1.5 MiB) TX bytes:191763 (187.2 KiB) Interrupt:11 Base address:0xc000 Memory:cffff000-cfffffff
The field HWaddr (in the highlighted line) contains the MAC address: 4f:A1:F1:C2:36:BF.
[edit] Finding your MAC Address on Windows
To find your MAC address on Windows, open a command prompt and type the following command: ipconfig /all. Look for the first line that begins Physical Address:...... The series of hexadecimal numbers at the end of that row is the MAC address for example, 4f:A1:F1:C2:36:BF. (If you have multiple Ethernet cards, you can use the MAC for any of them they are all unique.)
[edit] If You Don't Have a MAC Address...
If you do not have a MAC address, you can leave the field blank and OpenCms will generate a fake one for you, but you could run into problems if your ID matches somebody else's (though the chances of this are minuscule).
[edit] Continuing Installation
The next field instructs you to Enter the URL of your OpenCms site. It will attempt to generate a URL for you, usually with the domain name localhost. If your machine has a domain name, you may want to substitute that instead of localhost (e.g. http:// myhost.mydomain.com:8080). The following field is labeled Enter a name for your OpenCms server. This is used primarily for tagging log messages. If you are planning on running multiple instances of OpenCms on the same server, you should set this to a value that will identify this instance of OpenCms (e.g. MattsOpenCms), otherwise, you can leave this at its default.
Click Continue to run the module installer.
For the next several minutes, OpenCms will install and configure all of the modules you chose a few screens ago. This is processor, disk, and memory intensive, so the entire system will likely experience slowing.
Once the modules are installed, the Continue button at the bottom of the screen will be activated, and you can click it to go on to Browser configuration.
The information box describes the requirements for browsers that are going to access the online OpenCms Workplace (content authors, editors, and managers, as well as administrators will use the Workplace). OpenCms supports MS Internet Explorer 5.5 and up, as well as all browsers based on Mozilla 1.4 and up (that includes the Firefox browser). But you must enable JavaScript and cookies in your browser before you will be able to use Workplace. Additionally, you will need to allow popups from the OpenCms server.
Select the yes radio button and click Finish. This will take you to the final screen of the installation wizard.
Firstly, when this screen loads, a new window should pop up as well one that looks like this:
If the window does not pop up, you will need to change the settings to your pop-up blocker in order to allow OpenCms to open new windows.
Secondly, you may notice the warning message that says that the installer is now locked. That means that you (or anyone else, for that matter) cannot run the installer again without first unlocking it.
If for some reason you need to reinstall, you will need to unlock the installer. To unlock the installer, you will have to edit the file $CATALINA_HOME/webapps/ opencms/WEB-INF/config/opencms.properties and change the value of the property wizard.enabled (located at the very bottom of the file) to true. Only enable this if you must reinstall OpenCms, since it is a major security risk to have this flag enabled. At all other times, leave the value set to false.
Installation is now complete. You can safely continue on to the next tutorial to learn about the Workplace.
[edit] Manually Configuring Settings
On occasion you may need to set or alter some of operating parameters of OpenCms manually. This section briefly describes the configuration files that OpenCms uses.
The OpenCms configuration files are stored in a common directory: $CATALINA_HOME/ webapps/opencms/WEB-INF/config/. The opencms.properties file conforms to the Java standard for properties files. For the most part, the opencms.properties file contains database pool information, but it also contains the MAC address settings, the server name, and the property that determines whether the installation wizard is enabled (see above).
The rest of the files in the config/ directory are in XML. Here is an overview of what each file contains:
- opencms.xml: This file contains information on which Java classes OpenCms should load when it is configuring the server (at startup).
- opencms-system.xml: Many of the main configuration parameters for OpenCms are stored in this file, including information on which locales are available, parameters for cache tuning, and site configuration parameters. (It is possible in OpenCms 6 to host multiple sites on one instance of OpenCms.)
- opencms-modules.xml: We already had our first encounter with the concept of modules during installation of OpenCms. Every module has its own configuration directives. This file is where all of the settings for all installed modules are stored. After a clean installation, my
opencms-modules.xmlfile is over 2000 lines. Needless to say, it is tedious to edit this file. Fortunately, it is also rare that this file needs editing. - opencms-workplace.xml: The OpenCms Workplace is the "back office" component of OpenCms. This configuration file stores settings for the Workplace.
- opencms-vfs.xml: OpenCms stores content in the database, but in such a way as to mimic a standard file system. Since this system looks and acts like a file system, though it is not part of the server's actual file system, it is called the Virtual File System (VFS). The
opencms-vfs.xmlfile stores configuration parameters for the VFS. - opencms-search.xml: OpenCms has a built-in search engine one based on the fantastic Lucene Open Source search library. This file contains configuration parameters for OpenCms's search engine.
- opencms-importexport.xml: Like any good content management system, OpenCms can import and export its contents (this is useful for upgrading, backing up, or even migrating to another platform). This file makes it possible to fine tune aspects of that process.
While OpenCms should function fine without any modifications to any of these files, there are a few changes to one file that are worth making at this time.
Edit the opencms-system.xml file. In order to take advantage of email notifications in the Workplace, you will need to configure a few parameters in this file. Find the <mail/> element. It will contain several mail configuration elements:
<mail> <mailfrom>nobody@nowhere.com</mailfrom> <mailhost name="my.smtp.server" protocol="smtp" user="username" password="secure"/> <mailhost name="alternative.smtp.server"/> <mailhost name="another.alternative.smtp.server"/> </mail>
Set <mailfrom/> to the username you want OpenCms to send from. This address will show up in the From: field of outgoing email messages. The <mailhost/> element contains information about the SMTP mail server. The first attribute of this element is name. Set the value to the domain name of the SMTP server that it should contact. On Linux and UNIX machines that run Sendmail, this value can usually be set to localhost. The next attribute is protocol, which should be set to smtp for Simple Mail Transport Protocol the standard mail protocol used on the Internet. If your SMTP server requires authentication before a message can be sent (and this is increasingly common), you can use the user and password attributes to set the appropriate account information. If you want to set up "failover" mail hosts (so that if the first server is down, OpenCms can try another), you can simply create additional <mailhost/> elements and configure them accordingly. Otherwise, you should delete the extra <mailhost/> elements, since they will contain dummy data.
Any time you change one of these files, you will need to restart Tomcat in order for OpenCms to pick up the changes.
[edit] Summary
At this point, OpenCms is up and running inside the Tomcat Servlet container with a MySQL database, and configuration is complete.
[edit] Additional References
- For instructions on Customizing the OpenCms site, click here
- For instructions on Troubleshooting Installing Open CMS, click here
- For instructions in Building OpenCMS 7, click here.
- For instructions on Installing OpenCMS, click here
- For instructions in Developing Templates in OpenCMS 7, click here
[edit] Source
The source of this content is Chapter 2: Installing OpenCms of Building Websites with OpenCms by Matt Butcher (Packt Publishing, 2007).
