Skip to content

# goshoo/opencms-core forked from alkacon/opencms-core

### Subversion checkout URL

You can clone with
or
.
Fetching contributors…

Cannot retrieve contributors at this time

614 lines (487 sloc) 23.136 kB
 Installation

Installation of OpenCms 4.3.x

This chapter provides information on how to install OpenCms using all standard components described in the previous chapter. All installation parts are described as single steps. After completing a step you are strongly advised to verify the success by running the particular commands and watching the results.

If not mentioned, all commands refer both to UNIX and Windows systems. All shell commands containing path information are written in UNIX style using a slash "/" as folder separator. On Windows you will have to replace these characters by a backslash "\". Be very careful with replacing this characters since the virtual filesystem of OpenCms uses a slash. Using a backslash in virtual filenames will prevent OpenCms from running properly! Ensure that you really only replace slashes in shell commands and paths concerning the real file system.

You also will need a MS-DOS prompt in order to execute all commands in a Windows enviroment.

1 Installing the Apache Web Server

Install the Apache Web Server http://www.apache.org/httpd.html. Write down the document root path of the Apache containing all static HTML pages, your will need it later for configuring OpenCms. On WIN32 systems we recommend installing the Apache as service using apache.exe -i.

Run your web server by calling the httpd deamon in the Apache bin folder (UNIX) or starting the service (Windows). Check that it is working by requesting an example page (e.g. the demo index.html that comes with the Apache distribution).

2 Installing Java JDK and JSDK

Install the Java JDK (from SUN http://java.sun.com/products/j2se/ or IBM http://www3.software.ibm.com) and the Apache Jserv 1.1.2 from http://java.apache.org/jserv/index.html. For details on how to install these components on your operating system, see the documentation that comes with them.

Write down your JServ installation path. Like the Apache document root, you will need it later.

Make sure that you update the PATH environment variable with JDK bin directory, e.g. /usr/java/bin on UNIX and C:\jdk\bin on Windows systems.

Check that a JServ servlet zone is set up properly and running on your machine by requesting the default http://your server/servlets/IsItWorking class that comes with JServ.

3 Installing MySQL

Install MySQL from http://www.mysql.com/downloads/index.html (see the MySQL documentation on http://www.mysql.com/documentation/index.html).

Note: On Windows-based systems MySQL has to be installed on the C:\ drive and should be registered as service using (your MySQL path)/mysql/bin/mysqld -install.

Start the MySQL server by running the service (WIN32) or executing (your MySQL path)/mysql/bin/mysqld (UNIX).

Check that MySQL is running before you continue by starting the MySQL monitor (command 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.

4 Installing the OpenCms files

We currently do not have an RPM or setup.exe, but there are plans to make them available in the near future. We recommend that you unpack your OpenCms distribution archive file (opencms_4.3.yy from http://www.opencms.com/servlets/opencms/service/download.html) in your C:\Program Files\ folder on Windows systems and in the /opt folder on UNIX systems.

While extracting the ZIP archive a new folder opencms_4.yy (with yy replaced by the current build number) will be created. This new folder will be your OpenCms home directory. Make it to your current directory and check the content of the subfolder oclib. This folder is the right place for all external components and drivers used by OpenCms. In order to run OpenCms properly you should put the following JAR files in this folder:

• xerces.jar from the Apache Xerces XML parser.
• The MySQL JDBC database driver mm.mysql-2.0.1-bin.jar.
• mail.jar and activation.jar from the JavaMail distribution.
• fop_bin.jar (optional) from the FOP packet of the Apache XML project.

See the Components page on the OpenCms web site
(http://www.opencms.com/servlets/opencms/background/components.html) or chapter Components of the documentation for a more detailed description of these external parts of OpenCms.

5 Setting up the OpenCms database

For setting up the MySQL database for OpenCms, create a new database opencms42 by calling

(your MySQL path)/mysql/bin/mysqladmin create opencms42

It is important to name the database opencms42 because the configuration file of OpenCms ( opencms.properties) creates a database connection to a database named opencms42. If you want to use another name for your database you will have to change the line for the database connection in the opencms.properties file.

Run

(your MySQL path)/mysql/bin/mysql opencms42 < config/mysql.sql
This will create all of the required database tables. Make sure that all of the tables are created properly by calling the MySQL monitor again with

(your MySQL path)/mysql/bin/mysql opencms42

and entering

show tables
at the monitor prompt. MySQL should print the following list of tables:

+--------------------------+
| Tables_in_opencms42      |
+--------------------------+
| cms_files                |
| cms_groups               |
| cms_groupusers           |
| cms_module_forum         |
| cms_module_forum_comment |
| cms_projects             |
| cms_properties           |
| cms_propertydef          |
| cms_resources            |
| cms_sessions             |
| cms_systemid             |
| cms_systemproperties     |
| cms_task                 |
| cms_tasklog              |
| cms_taskpar              |
| cms_tasktype             |
| cms_users                |
+--------------------------+

On success, you now can exit MySQL simply by typing

exit

6 Initializing the OpenCms database

Edit the opencms.properties file in the config folder of your OpenCms home directory and set the path for the log file:

log.file=(your OpenCms home directory)/logs/opencms.log

On UNIX systems, Apache may have problems writing to the logs folder. For this reason you should set its owner to nobody.

OpenCms is able to export folders to the real file system on the server during publishing operations. This feature commonly is used for storing pictures or large downloadable binary files in the Apache Web Server's document root. This will increase performance while displaying web pages with OpenCms. We recommend to set the following export paths in the opencms.properties file:

exportpoint.0 = /pics/
exportpoint.path.0 = (real path to apache document root)/pics/
exportpoint.1 = /download/
exportpoint.path.1 = (real path to apache document root)/download/
exportpoint.2 = /system/workplace/pics/
exportpoint.path.2 = (real path to apache document root)/pics/system/

Note the trailing slash characters. They are very important and must not be omitted.

Ensure that all paths you are using as export points in your real file system do really exist. OpenCms won't try to create these folders.

Similar to the log file on UNIX systems access rights conflicts may occur while OpenCms is trying to write to these folders. Set their owner to nobody, too.

Now take a look at the file cmssetup.txt: Set the path for OpenCms export files appropriate to your system by editing the line beginning with "writeExportPath" to

writeExportPath "(your OpenCms home directory)/export/"

(you will find these lines near to the end of the file). Again the trailing slash is very important.

Make the OpenCms home directory to your current directory again and initialize the database with all workplace default files by calling the following command:

java -mx64M -jar opencmsboot.jar < config/cmssetup.txt

Note: The Java binary java should reside in the bin folder of your JDK installation. If you have added this folder to your system PATH environment as recommended during the installation of the Java VM, this command should work without giving a path.

If you have a Java runtime environment on your system rather than a complete JDK, you can replace the java command by jre.

If there are errors, check the database connection configuration in your opencms.properties. Also ensure you are using Java 1.2 or higher since previous versions are not able to start a JAR file.

After fixing a problem, you should drop ( mysqladmin -user=root -p drop opencms42) and recreate the existing database opencms42 (see previous section) before running the command above for a second time.

After this the OpenCms database setup is completed. You are now able to check the basic OpenCms system. Call the OpenCms console by entering:

java -mx64M -jar opencmsboot.jar

This command is similar to the one above. Note that the part " < config/cmssetup.txt" is missing now.

Log in as Admin and check the accessibility of a workplace file in your database. You execute these commands on the shell:

login Admin admin
readFile "/system/workplace/action/start.html"

The OpenCms console answers e.g. with

[Resource]:/system/workplace/action/start.html,
Project=1 , User=2 , Group=3 : Access=rwvr------ : Resource-type=2 : Locked=-1 : lenght=168 : state=0

Quit the console by typing exit.

7 Configuring your servlet zone

Finalize the configuration of your servlet zone. Make sure that your jserv.conf in the conf folder of your Apache JServ installation directory contains the line

ApJServMount /servlets /root
Note: ApJServMount, /servlets and /root are separated by blanks. The file jserv.properties in the JServ conf folder must contain
zones=root
wrapper.bin.parameters=-mx64M
root.properties=(your servlet configuration path)/zone.properties
Note: On Windows systems you should use a backslash instead of a slash. Update your zone.properties and set the following repository:
repositories=(your OpenCms home directory)/opencmsboot.jar

and add to the Servlet Aliases section the line:

servlet.opencms.code=com.opencms.boot.OpenCmsServlet

and to the Aliased Servlet Init Parameters section

servlet.opencms.initArgs=opencms.home=(OpenCms home)

After configuring your servlet zone you should restart the Apache to ensure the new settings are read by the servlet engine.

8 Now your system is ready

Start your web server. The OpenCms system is available at
http://your.server/servlets/opencms/system/workplace/action/login.html.
Login as Admin using the default password admin.

9 Security

After you have installed OpenCms you should look at the security. Change the Admin password of OpenCms by calling the user preferences ("hammer" icon on the main screen of the workplace). Then can add a password to the MySQL database. Enter the following commands at the MySQL command line.

use mysql;
insert into user values ('localhost', 'ocmsuser',
password('XXXXX'),'N','N','N','N','N','N','N','N','N',
'N','N','N','N','N');
insert into db values ('localhost', 'opencms42', 'ocmsuser',
'Y','Y','Y','Y','Y','Y','Y','Y','Y','Y');
flush privileges;

Don't forget to add the new user and password to all connect strings of the database to your opencms.properties. The new user can now only connect to the OpenCms tables. For more information see the MySQL documentation.

10 Troubleshooting

Look at all of the available log files (here with the paths used in a standard UNIX installation) if you have problems calling the login screen:

• Apache log file (usually (Apache home)/logs/error_log)
• JServ module log file (usually ((JServ home)/logs/mod_jserv.log)
• OpenCms log file ( (OpenCms home)/logs/opencms.log)

11 Installation of the example news module

The setup of the basic system is now complete, but you may want to add some more functionality to it. A good way to get used to the system is to practice with the module mechanism and to install a first module.

A simple newsfeed module came with the basic system or can be downloaded from the opencms homepage. The installation of the module is quite easy.

• Unzip the file NewsModule.zip. The zip-file contains two files: another zip containinig the real module ( com.opencms.modules.homepage.news_2.zip) and a script to set up the MySQL database ( NewsModuleSetup.sql).

• First prepare the database. Change to the folder in which the file
NewsModuleSetup.sql resides and type in the following shell command:

(your MySQL path)/bin/mysql opencms42 < NewsModuleSetup.sql

This creates all necessary tables and inserts some test data.

• Then upload the module. Move the file
com.opencms.modules.homepage.news_2.zip to the modules subdirectory in your export path.

Open the OpenCms workplace and change to the module management under the administration view. Make sure that you are within the online project. Choose the icon to upload a new module. Choose upload new module from server and continue.

The module should appear in the selectbox. Select continue to start uploading the module.

If all went well, the module is now installed. The module provides two new administration points. A further documentation can be found in the virtual filesystem.

Start exploring under /moduledemos/com.opencms.modules.homepage.news/.

12 Setting up a local copy of the OpenCms homepage

You can complete your test system by setting up a local copy of the OpenCms homepage. The OpenCms homepage uses the news module, so it is necessary to install the module if you want to make your first steps with the OpenCms homepage.

To get the templates of the OpenCms homepage you have to make a simple import. The required import file (\name website_import.zip) is shipped with OpenCms 4.2, together with another sql-script (\name website.sql). This script inserts the content which is handled by the News Module into the database. Both files are bundled to the zip file \name website.zip.

• Extract this file first and then move the file \name website_import.zip to your export path.

• Then insert the content into the database by using the sql-script. Change to the folder in which the file website.sql resides and type in the following shell command:

(your MySQL path)/bin/mysql opencms42 < website.sql

• Then you have to import the templates. To be able to do this, you have to be within a project (not the online project), so create a new project first.
Change to the administration view and choose Projectmanagement -> New Project.
Specify a project name, for example OpenCmsHomepage and the folders that should be included.
In this case include everything, type in / and press the button with the blue arrow to adopt this directory to the list of folders that have to be included.

After creating the new project, make sure that you are actually inside it and change again to the administration view.

• Now start the import of the OpenCms homepage. Make sure that the import file
website_import.zip can be found within your export directory. Choose the point Databasemanagement and then import. Choose the file website_import.zip from the selectbox and start the process.

That's all.
Note: The pictures are missing right now, but they will be available after publishing the project.

13 Setting up OpenCms with different components

OpenCms is developed and tested in the environment described in chapter \ref Unknown LaTeX command \ref components . Since the system is based on standards and written 100% in Java, it should be easy to use other components.

Global and detailed instructions for all possible constellations of components would go out of the scope of this documentation. However, we are very interested in descriptions on how to set up OpenCms with other well-known and commonly used environments.

If you managed to set up OpenCms with different components, please let us know. You can send your configuration information to documentation@opencms.com.

13.1 Installation on Solaris with BEA Weblogic 5.1 and Oracle 8

Heiko Kirschke has set up OpenCms on a Solaris system with a BEA Weblogic 5.1 application server using an Oracle 8 database. He sent us the follwing annotions. All step numbers refer to the corresponding steps in the instructions for the reference system.

If you have questions concerning these instructions, please directly contact Heiko Kirschke (mailto:Heiko.Kirschke@acm.org).

• Step 1 Installing Apache is not necessary for BEA Weblogic, since BEA WebLogic has its own Web server. Use this URL instead: http://your.server:7001, this should come up with the standard BEA page.

• Step 2 For BEA WebLogic, install the J2EE additionally. Set up an environment variable J2EE_HOME which points towards this installation directory.

Installing Apache JServ is not necessary for BEA Weblogic, since BEA WebLogic has its own servlet engine.

• Step 3 With BEA WebLogic, normally Oracle (or one of the other major commercial RDBMs) is used. Haven't checked BEA WebLogic with mySQL up to now.

• Step 4 Assuming that $WL_HOME points towards the BEA WebLogic installation directory (e.g.$WL_HOME=/usr/local/weblogic), create directory
$WL_HOME/myserver/servletclasses/opencms and put these files there. I prefer to use a symbolic link  opencms' here, with  opencms' being a symbolic directory link to the current used OpenCms version. The document root folder is$WL_HOME/myserver/public_html

In BEA WebLogic, (your servlet path)/servlets becomes
$WL_HOME/myserver/servletclasses/opencms, i.e.:$WL_HOME/myserver/servletclasses/opencms/ExternalComponents/xerces.jar
$WL_HOME/myserver/servletclasses/opencms/logs/$WL_HOME/myserver/servletclasses/opencms/opencms.jar
$WL_HOME/myserver/servletclasses/opencms/opencms.properties • Step 5 In BEA WebLogic with Oracle, start sqlplus and source in the Oracle setup script, e.g.: sqlplus ... <login to DB etc.> @oraclePlsql.sql quit Be aware that this erases all pre-existent OpenCms data of previous OpenCms installations. • Step 6 In BEA WebLogic, I use the log file$WL_HOME/myserver/servletclasses/opencms/logs/opencms.log

Use the document root instead of the (your apache docroot) as described above, i.e.:

registry = (your opencms folder)/config/registry.xml
exportpoint.path.0 = $WL_HOME/myserver/public_html/pics/ exportpoint.path.1 =$WL_HOME/myserver/public_html/download/
exportpoint.path.2 = $WL_HOME/myserver/public_html/pics/system/ I have a special Solaris user and group weblogic which owns all BEA WebLogic files (i.e., all files including and below$WL_HOME).

• Step 7 Add following lines to $WL_HOME/weblogic.properties (replace (path to servletclasses) by the complete path of your servletclasses subfolder in your local$WL_HOME installation directory):

weblogic.httpd.register.opencms=com.opencms.core.OpenCmsServlet
weblogic.httpd.initArgs.opencms=\
properties=/(path to servletclasses)/opencms/opencms.properties

Change following lines in $WL_HOME/startWebLogic.sh from: PRE_CLASSPATH= POST_CLASSPATH= to: PRE_CLASSPATH="${WL_HOME}/myserver/servletclasses/opencms/opencms.jar:
${WL_HOME}/lib/xerces.jar:${J2EE_HOME}/lib/j2ee.jar"

POST_CLASSPATH="${ORACLE_HOME}/jdbc/lib/classes12.zip:${ORACLE_HOME}/jdbc/lib/nls_charset12_01.zip"

This assumes that $ORACLE_HOME points towards your Oracle installation directory, since the Oracle driver classes are loaded from there.$J2EE points towards your J2EE installation. I've put the xerces.jar into $WL_HOME/lib instead into the ExternalComponents directory. • Step 8 For BEA WebLogic, use this URL instead: http://your.server:7001/opencms/system/workplace/action/login.html. • Step 10 BEA WebLogic puts its logging entries into$WL_HOME/myserver/weblogic.log

Something went wrong with that request. Please try again.