34,79 €
Mehr erfahren.
- Herausgeber: Packt Publishing
- Kategorie: Wissenschaft und neue Technologien
- Sprache: Englisch
This book takes you through the process of creating content-rich websites and applications using OpenCms. Although powerful and flexible, OpenCms can be daunting on first approach, but its advanced features reward the investment in learning. This book exists to ease Java developers into getting the most from OpenCms.
OpenCms OpenCms is a professional-level, open source Website Content Management System, with which you can create and manage complex websites. Based on Java and XML technology, it fits into almost any modern IT environment. With hard-won experience of the practical difficulties faced by developers working with OpenCms, this book is the embodiment of the author's expertise, and the perfect way to master the system.
Das E-Book können Sie in Legimi-Apps oder einer beliebigen App lesen, die das folgende Format unterstützen:
Seitenzahl: 413
Veröffentlichungsjahr: 2004
Ähnliche
Table of Contents
Building Websites with OpenCms
Matt Butcher
Building Websites withOpenCms
Copyright © 2004 Packt Publishing
All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews.
Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the author, Packt Publishing, nor its dealers or distributors will be held liable for any damages caused or alleged to be caused directly or indirectly by this book.
Packt Publishing has endeavored to provide trademark information about all the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information.
First edition: June 2004
Published by Packt Publishing Ltd.
32 Lincoln Road
Olton
Birmingham, B27 6PA, UK.
ISBN 10: 1-904811-04-3
ISBN 13: 978-1-90481-104-6
www.packtpub.com
Cover Design by www.visionwt.com
Credits
Author
Matt Butcher
Technical Reviewers
Olli Arro
Paul D Bain
Alex Epshteyn
Stephan Hartmann
Harald Gottlicher
Layout
Niranjan Jahagirdar
Commissioning Editor
Douglas Paterson
Technical Editor
Niranjan Jahagirdar
Indexer
Ashutosh Pande
Proofreader
Chris Smith
Cover Designer
Helen Wood
About the Author
Matt Butcher is the Principal Consultant for Aleph-Null, Inc., a systems integrator located in Colorado, USA. Specializing in open-source software, Matt has worked on a wide variety of projects, including embedding Linux in set-top boxes and developing advanced search engines based on artificial intelligence and medical informatics technologies. Matt is involved in several Open Source communities, including OpenCms, Gentoo Linux, and RT (Request Tracker). In addition to his software development, Matt has worked as a freelance journalist covering areas of interest to the Open Source community. When Matt is not working, he enjoys exploring Colorado with his wife and his two daughters.
When I first started working with Open Source developers, I thought it was all about the software. After years of work with some fantastic people from many nations and walks of life, I realize that the software is an added benefit, but it is really all about the people and the community.
Thanks to Olli Arro, Joachim Arrasz, Paul D. Bain, Alex Epshteyn, Harald Gottlicher, Stephan Hartmann, Niranjan Jahagirdar, Douglas Paterson, and Ernesto De Santis, each of whom contributed (directly or indirectly) more to this book than I could describe here. Thanks also to Rene van't Veen for the SQL Server query.properties patch and Geoff Winkless for his SQL Server stored procedures.
I'd also like to thank the members of the OpenCms developers' list who have proved an invaluable resource in all of my OpenCms projects, and especially in writing this book.
And, of course, Alexander Kandzior and the OpenCms developers for building a great product around which an even greater community has formed.
Thanks to JP and Jonathan Marsden from Global Resources for Computing for initially allowing me to contribute the OpenCms Lucene module, and for providing me flexible work during the writing of this book.
Also, thanks to Dr. Wes Munsil and Janet Siebert for lending technical expertise as well as their encouragement.
Special thanks to Angie, Annabelle, and Claire for their encouragement.
Introduction
OpenCms is an open-source enterprise-grade content management system based on Java and XML technology, and is designed specifically for creating and maintaining websites. It provides a full set of tools for dealing with content creation, editorial workflow, publishing, and versioning.
In this book we will take you through the process of constructing an OpenCms website, showing you how to work with OpenCms, customize and extend your system with Java libraries and classes, JSP pages, and XML templates, and how to administer and deploy your OpenCms solution.
Like many of the open-source content management systems, OpenCms is daunting on first use, but its power and flexibility reward the investment in learning to use it. This book exists to ease you into getting the most from OpenCms.
What This Book Covers
Chapter 1 gives us an introduction to OpenCms, its features, and its history. Chapter 2 walks us through the process of installing and configuring OpenCms. We look at installing OpenCms with its setup wizard, securing and troubleshooting the installation, and configuring the client.
Chapter 3 explores the OpenCms Workplace; this is the primary interface for managing the contents of your OpenCms repository, and includes tools for editing, project management, workflow, publishing, and server administration. In this chapter, we cover various aspects of working in the OpenCms Workplace, including managing projects, using modules, permissions, editing and publishing documents, creating new pages, and customizing the Workplace.
In Chapter 4 we turn our attention to customizing the site. We look at developing the look and feel of published content, adding dynamic elements, and controlling resources. This includes topics such as working with templates, using OpenCms JSP tag libraries, creating JSP scriptlets, and managing FlexCache directives.
Chapter 5 takes us into the heart of OpenCms, looking at the mechanisms that drive the content management system. We look at resource types, content definitions, the Virtual File System (VFS), and the class structure of OpenCms.
In Chapter 6 we look at OpenCms modules; these provide a mechanism for extending the functionality of OpenCms. Modules are designed to be easily distributed among OpenCms installations, and can provide functional elements ranging from portable content to sophisticated applications that interact with content in OpenCms. We take an in-depth look at developing modules, covering topics such as creating a module, adding templates, content, and JSP pages to the module, adding custom Java classes and libraries, and exporting and deploying your module.
Chapter 7 tackles some advanced features of the OpenCms module mechanism. We cover creating an administration point for a module, using JSPs to produce administration screens, and creating a custom launcher class.
In Chapter 8 we return to the administrative aspect of managing OpenCms, and examine the issues surrounding the deployment of an OpenCms solution. We cover static exports, user authentication and management, and other administrative tasks such as backup, recovery, and performance tuning.
There are two appendices that cover building OpenCms from its sourcecode, and installing, configuring, and using the OpenCms Lucene Module to improve the searching of your site.
What You Need for Using This Book
To use this book, you will of course need OpenCms. This is freely downloadable from http://www.opencms.org/opencms/en/download/opencms.html.
OpenCms has its own requirements for installation: Java 2 SDK version 1.4 or higher, Apache Tomcat 4.x, and MySQL 3.23.x or higher.
You will find details of where to download these applications from in Chapter 2, but each is freely available.
A sound knowledge of Java, JSP, and XML will help you get the most out of this book.
Reader Feedback
Feedback from our readers is always welcome. Let us know what you think about this book, what you liked or may have disliked. Reader feedback is important for us to develop titles that you really get the most out of.
To send us general feedback, simply drop an e-mail to <[email protected]>, making sure to mention the book title in the subject of your message.
If there is a book that you need and would like to see us publish, please send us a note in the Suggest a title form on www.packtpub.com or e-mail <[email protected]>.
If there is a topic that you have expertise in and you are interested in either writing or contributing to a book, see our author guide on www.packtpub.com/authors.
Customer Support
Now that you are the proud owner of a Packt book, we have a number of things to help you to get the most from your purchase.
Downloading the Example Code for the Book
Visit http://www.packtpub.com/support, and select this book from the list of titles to download any example code or extra resources for this book. The files available for download will then be displayed.
Note
The downloadable files contain instructions on how to use them.
Errata
Although we have taken every care to ensure the accuracy of our contents, mistakes do happen. If you find a mistake in one of our books—maybe a mistake in text or code—we would be grateful if you could report this to us. By doing this you can save other readers from frustration, and also help to improve subsequent versions of this book.
If you find any errata, report them by visiting http://www.packtpub.com/support, selecting your book, clicking on the Submit Errata link, and entering the details of your errata. Once your errata have been verified, your submission will be accepted and the errata added to the list of existing errata. The existing errata can be viewed by selecting your title from http://www.packtpub.com/support.
Questions
You can contact us at <[email protected]>if you are having a problem with some aspect of the book, and we will do our best to address it.
Chapter 1. Introduction to OpenCms
The purpose of this chapter is to provide a brief introduction to OpenCms and the concepts and technologies it employs. In this chapter, we will cover:
What Is a Content Management System?
The exact definition of a CMS is somewhat slippery, as the range of CMS systems is broad and the functionalities of each differ markedly. At the core, however, a content management system provides a framework for creating, managing, and publishing documents and texts. In more practical terms, a content management system handles the process of creating and maintaining a collection (large or small) of documents.
While CMS systems in general deal with a wide variety of types of collections, ranging from memos to marketing material, web-based collections are the most high profile. To that end, many CMS systems, including OpenCms, focus on web-based management (also called Web Content Management or WCM) and delivery of content.
Three Essential Components
There are three essential components to an enterprise-class CMS:
Editorial workflow refers to the process of preparing a piece of content for production. In the simplest case, this may simply involve one person writing a document, proofing it, and perhaps also revising it. However, in a larger context, the process may involve multiple authors writing content that is then edited by a team of editors and producers. A manager may assign a topic to an individual author who then writes a document. Once the author is done with the document, a team of editors reviews and corrects it, occasionally handing it back to the author for revision. Once this iterative process is complete, the editors submit the document to a producer, who makes decisions about whether the content is to be distributed, and if so, when. A good CMS must handle both the simple and the complex cases of editing. Once a document is written, it must be published.
Publishing is the next step in the life of the document. Publishing the document makes it accessible to potential readers. Some collections of content, such as the numerous chapters in a manual, are all published together. Other content, such as a news article or a press release, may be published on its own without requiring simultaneous publishing of other material. Sometimes images need to be published along with a particular document. Sometimes the document may require a certain amount of dynamic information (such as stock quotes or live images) to be incorporated. All of these possibilities mandate an effective publishing mechanism. A document's life cycle is not complete once it's published—it now enters version control.
Versioning becomes important once a document has been published. Authors and editors may make corrections or add updated information, and these changes may require their own editorial cycle before they can be published. Changes to the document should not be immediately incorporated into the published version, but must remain in the editorial stage while the currently published version remains available. Even after the changes are published, circumstances may require that the update be 'backed out' and the prior version restored. This process of revising and updating a document while preserving a record of changes is called versioning.
What Is OpenCms?
OpenCms is an open-source enterprise-grade content management system designed specifically for maintaining websites. It provides a full set of tools for dealing with content creation, editorial workflow, publishing, and versioning.
OpenCms is released under the Lesser GNU Public License (LGPL), which is an Open Source Initiative (OSI) certified open-source license created by the Free Software Foundation. Since OpenCms is released as open source, its source code is available from the OpenCms website.
The LGPL dictates that the source code for OpenCms must be made freely available. The source code for any changes made to it must also be made freely available.
However, external components, such as modules, wrappers, or JSP files, are not restricted by the LGPL, and can use different licenses (including proprietary, 'closed-source' licenses). This gives the application developer the power to decide how many restrictions should be placed on the code.
Note
For more information on the LGPL, see the following websites:
OpenCms: http://www.opencms.org/The Free Software Foundation's LGPL License: http://www.gnu.org/licenses/licenses.html#LGPLThe Open Source Initiative: http://www.opensource.org/
Features
OpenCms is a web application. It runs on a web server and is accessed and used via a web browser. The following list discusses its features:
History
Alexander Kandzior began tinkering with content management software in 1994. By 1998, the pieces began to come together into a single content management system. In March 2000, the OpenCms Group, a loose collection of individuals working on the system, released OpenCms under an open-source license.
Under the auspices of the OpenCms Group, a number of companies and individuals contributed to the formation of OpenCms, but by the time OpenCms reached version 5.0 in 2002, some of the original members of the group were ready to move on to new projects. The OpenCms Group was dissolved.
Wanting to continue the development of his code, Alexander Kandzior started a new company, Alkacon Software, which took the reins of the OpenCms project. Alkacon Software now maintains the project, providing the roadmap and release cycle, as well as contributing code to OpenCms. To fund ongoing development of OpenCms, Alkacon provides support contracts, training, and consulting services.
Alexander and the Alkacon team are a visible presence in the community, and Alexander often contributes help and advice on the public OpenCms developer's list.
The OpenCms Community
Like many open-source projects, OpenCms has a lively community of developers and users. Many software developers contribute code directly to OpenCms. Others create add-on modules to provide additional services and features. Many more simply use the product. All three of these groups participate on mailing lists and forums surrounding OpenCms.
With many active contributors, the opencms-dev mailing list is a great resource for help installing, configuring, and developing OpenCms. In addition to providing help, the list is also a useful source of code and new modules.
Note
To join the opencms-dev mailing list, go to: http://www.opencms.org/opencms/en/development/mailinglist.html
The list archives are available at: http://www.opencms.org/opencms/en/development/mailinglist-archive.html
Also, the 'unofficial' OpenCms forums hosted by Synyx oHG provides an online forum for discussion. The forum has a section for HowTos, and sample code generated by members of the community. Finally, the OpenCms Modules and Tutorials section mentions the al-arenal.de website. While OpenCms.org hosts completed modules on its website, developers will often release beta modules, modifications of existing modules, and 'semi-formal' documentation on this unofficial OpenCms website.
Note
These 'unofficial' sites provide useful information on OpenCms:
The OpenCms Forums: http://synyx.de/board/OpenCms Modules and Tutorials: http://opencms.al-arenal.de/Online OpenCms demo: http://demo.comundus.com/
The Purpose of This Book
This book is intended to provide detailed information for those interested in developing and deploying OpenCms-based sites. It is assumed that the reader is familiar with installing software and managing either Windows 2000 or Linux/UNIX. Because much of this book is dedicated to writing HTML, Java Server Pages, and Java code, having a working knowledge of these technologies is necessary.
Technical Overview
OpenCms is written in Java. It makes use of industry-standard XML (eXtensible Markup Language), and uses Java DataBase Connectivity (JDBC) to store data in a relational database. Built in Java, OpenCms can run on different platforms, including numerous versions of UNIX and Linux, and Windows.
Hardware-wise, OpenCms is designed for scalability. It will run on hardware ranging from small laptops (I've run it on a Pentium III 733 Toshiba Tecra laptop with 256 MB RAM and Red Hat 8) to a distributed collection of servers.
Being a web-based application, OpenCms runs as a Java servlet inside a servlet container such as Apache Tomcat or BEA WebLogic. For data storage, it can use a number of SQL databases, including MySQL, Microsoft SQL Server, and Oracle.
At one time, OpenCms required developers to learn a proprietary XML schema for developing templates, but in version 5.0, OpenCms has changed direction and now uses Java Server Pages; we'll get into the details of the system later. Here is a brief summary of how each of these components works (and how they all work together).
The Web Server and Java Servlets
The web server handles incoming connections. As it sees connections intended for OpenCms, it hands them off to the servlet container for processing. The servlet container manages one or more Java servlets. Unlike a CGI script, which runs only for the amount of time it takes to process a single request, a servlet stays running until the server explicitly stops it (which usually only happens when the server shuts down). The job of the servlet container is to provide the runtime environment for the servlets.
While it is possible to run OpenCms on the command line, it is almost always run as a servlet.
The Database
OpenCms uses a database for persistent data storage. Information about file types, templates, and publishing is stored in the database, as is all the content. OpenCms supports a couple of major SQL-based databases, including MySQL, Microsoft SQL Server, and Oracle. Developers are working on ports to PostgreSQL and other databases.
OpenCms uses JDBC to connect the Servlet to the database during startup. Content is managed inside the database, though it can be exported from the database into static files during a publishing cycle.
Pages, Templates, and Java Server Pages
Content is stored in the database in the form of XML files. Layout information and processing code is also stored in the database, but not in the same XML document as the content. When a page is requested, the content is pulled out of the database and put into a template. Any special processing needed is run, and the results are sent back to the requester (usually a web browser) in the form of a complete HTML file.
Templates and custom code are written in two languages: XML Template, a simple XML-based language developed by the OpenCms team, and Java Server Pages, a standardized language for embedding Java processing instructions inside of an HTML or XML document. While XML Template is still used in OpenCms 5, it will be phased out and replaced by the more flexible and mature JSP technology in future releases.
Bringing it Together
Each of these pieces functions together for each request. A typical response to a document (we'll call it test.html) might look like this:
Summary
By now, you should be familiar with the basics of OpenCms—its uses, history, and key components. The next chapter will cover the installation of OpenCms, and subsequent chapters will discuss the use of and development on OpenCms.
Chapter 2. Installing OpenCms
This chapter walks through the process of installing and configuring OpenCms. In the last chapter, I mentioned that OpenCms can run on a wide range of platforms and configurations; this chapter focuses on the two most common platforms: Linux/MySQL/Tomcat and Windows 2000/MySQL/Tomcat. Generally speaking, installation on other platforms is similar enough for these instructions to suffice. In this chapter, we will cover:
Prerequisites
OpenCms will need a configured database and a functioning servlet engine. We will use MySQL for the database and Tomcat for the servlet engine. Since OpenCms uses the ISO 8859-1 character set, I will explain how to configure Tomcat to use that character set as default. Additionally, I will cover the registry settings that Windows installations require.
To install these packages on Linux, you will need to be root unless your system administrator has configured your system in a way that you can install these packages a different way (such as using sudo).
In Windows 2000, you will need to install the software as the Administrator user.
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 MS SQL Server, MySQL runs on Windows and Linux, is free, and is the database on which OpenCms developers work.
OpenCms 5.0 can use either the 3.23.x or the 4.0.x version of MySQL. On Linux, if you are comfortable with MySQL, you may prefer to get the latest release from the MySQL website. However, if you are new to MySQL it is best to use the version your distribution contains (for example, at the time of this writing, Red Hat still used 3.23.x, while Gentoo used 4.0.x). That way, you can rely on your Linux vendor to provide updates and fixes.
On Windows, it is best to use the newest stable release from the MySQL website (at press time, 4.0.18 was the latest release).
MySQL on Linux
There are a couple of ways to install MySQL on a machine running Linux. You may decide to build the database from the source code, or you may download and install the binary provided by MySQL. Most Linux distributions provide a MySQL package (and often, it is installed already)—this is usually the best version to install.
Note
OpenCms does not require that the database be on the same machine as the servlet engine. OpenCms simply needs access to the database over the network (via JDBC).
To install the database, consult the documentation for your Linux distribution and that on the MySQL website http://www.mysql.com/documentation/index.html.
Many Linux distributions turn off network-based database connections by default, so you may need to manually enable the network-based server. Usually, this simply involves editing the /etc/my.cnf file. In the [mysqld] section, add the line port=3306. Consider the following relevant portion of my my.cnf file:
Make sure the database is running before proceeding. Most Linux systems provide init scripts for starting and stopping services. These scripts are usually located in /etc/init.d/. For instance, in Gentoo you can check to see if the database is up by running the command /etc/init.d/mysqlstatus. If the server is not running, using the command start instead of status will start the server.
Once the database is running, you are ready to move on to finishing the MySQL setup.
MySQL on Windows
While it is possible to build MySQL from source on Windows, it is much easier to download the Windows binary from the MySQL site and install it. Detailed documentation can be found at http://www.mysql.com/documentation/index.html.
Note
Windows users may find it helpful to download the MySQL documentation in CHM or HLP help-file formats. They can 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:
Alternately, if the MySQL icon appears in your taskbar, 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 taskbar icon, or typeNETSTARTmysql at the command prompt.
Finishing the MySQL Setup
Once MySQL is running, set the 'root' password. This 'root' user has total control over the database, but is not necessarily correlated with the root or administrator accounts on the operating system.
Note
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:
In the command above, -uroot indicates that you are connecting to the database as the root (administrative) user. -p provides an interactive password prompt, and mysql at the end indicates the database that we will use (mysql is the name of the administration database for MySQL). Once you have connected to the database, it is time to create the opencms database and the user accounts that OpenCms will use to connect to that database.
The MySQL command for creating a database is CREATEDATABASE[dbname]. So the command to create a database named opencms is:
Make sure you include the semicolon at the end of the line. Now, create the opencms user:
This statement gives permission to add, delete, and modify tables in the opencms database to the user opencms@localhost, whose password is mypassword. If OpenCms is to be run on a different machine than 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).
The database is now prepared for OpenCms. It's now time to configure the servlet engine.
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 the standard.
Before you can run any Java applications, you will need to install the Java System Development Kit (JSDK). OpenCms 5.0 is written to take advantage of the features of JSDK 1.4, 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.
Note
Windows and Linux do not include the JSDK by default. If Java is not already installed, you can obtain Sun's version for free from http://java.sun.com/. At the time of writing this, neither IBM's JDK nor Blackdown's JSDK had reached the 1.4 specification, and so neither will run OpenCms.
For this book, I 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 that OpenCms developers use. Tomcat source and binaries are available from http://jakarta.apache.org. The binary releases are almost always suitable for use, but you may download and compile the source code if you prefer. While there are releases for version 5, which implement the new 2.4 servlet specification, OpenCms was developed according to the 2.3 servlet specification. Therefore, it's best to use a 4.1.x release of Tomcat (4.1.30 is the current stable release).
To install Tomcat on either Windows or Linux, simply 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. If you choose to install it this way, do not check the box that automatically configures Tomcat as a service. Later in this chapter, I will explain how to configure Tomcat as a Windows service.
Linux Configuration
In Linux, Tomcat is generally installed into /opt/tomcat or /usr/local/tomcat. Assuming the former location, set the CATALINA_HOME variable by running the following command:
Also, make sure that the JAVA_HOME environment variable is set. You can check by running env|grepJAVA_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):
To start Tomcat with this script, you may just type ./tomcat.shstart, and to stop it, use ./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).
Windows Configuration
Whether you have installed with the graphical installer or by simply unzipping the archive into a directory, you will need to set two environment variables: CATALINA_HOME and JAVA_HOME. In Windows 2000, you can do this by right-clicking on My Computer and choosing Properties. Go to the Advanced tab. Select Environment variables and create two variables: CATALINA_HOME pointing to the Tomcat installation (e.g. C:\ProgramFiles\ApacheGroup\Tomcat4.1), and JAVA_HOME pointing to the J2SDK directory (e.g. C:\j2se1.4.2).
Because the Windows services do not use environment variables and OpenCms requires that extra options be passed into Tomcat, Tomcat must be installed from the command line rather than the graphical installer. Open up a command prompt, change the directory to Tomcat's bin directory with cd%CATALINA_HOME%\bin, and run the tomcat-install command as it is displayed below. Even though the following has been split for readability, it must be typed on just one line in order to run correctly:
After this has run, you should see a message saying something like:
If you ever need to uninstall the service, issue the tomcat-uninstallTomcat command.
As with MySQL, Tomcat can be started and stopped either through the Windows Service utility or from the command line withNETSTARTTomcat and NETSTOPTomcat.
Note
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 IIS.
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, using this URL is easier. For the remainder of this book, I 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. Alternatively, you may instead 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.
Note
To configure Tomcat to listen on the standard HTTP port, make sure you are not running another web server already, and then edit theserver.xml file (under $CATALINA_HOME/conf/ in Linux, %CATALINA_HOME%\conf\ in Windows). Find the ConnectorclassName="org.apache.coyote.tomcat4.CoyoteConnector" element and change port="8080" to port="80". You will need to restart Tomcat before the change takes effect. Now, the URL no longer needs :8080 at the end.
Configuring Encoding
There is one last step to configuring the environment before installing OpenCms. By default, OpenCms uses the ISO 8859-1 character set (sometimes referred to as the Latin-1 character set). To make sure that Tomcat uses this character set, you must pass it a special parameter: -Dfile.encoding=ISO-8859-1. In the Linux start script, I included a line that set this parameter as a value ofCATALINA_OPTS. I also specified the parameter in the online command for adding Tomcat as a service on Windows. However, if you intend to start Tomcat with other tools, you can add the parameter to the catalina.sh (for Linux) or catalina.bat (for Windows).
OpenCms supports other character sets. Later in this chapter, I will cover configuring and using the UTF-8 character set, which supports multi-byte characters.
Note
The step of configuring character encoding is often overlooked, as it appears to be unimportant or unnecessary. However, not configuring encoding can result in strange, seemingly inexplicable errors.
After configuring encoding, restart Tomcat and make sure the default URL loads in your browser. Now that Tomcat and MySQL are configured, it's time to install the OpenCms Web ARchive (WAR) file.
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 (which we used for setting encoding) to set initial and max heap sizes. The example below sets the encoding to ISO-8859-1 (the default for OpenCms), and then 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 1 Gigabyte RAM, though you could certainly experiment with more aggressive settings.
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 can be quite noticeable.
Installing the OpenCms WAR File
As with most open-source projects, OpenCms is available in both source and binary releases. In Appendix A, I cover building OpenCms from source, but in this section, I will refer only to the binary build. Download the 5.0.1 release (opencms_5.0.1.zip) from http://www.opencms.org/opencms/en/download/index.html, the OpenCms downloads page.
OpenCms, like most Java servlets, is packaged in a WAR file. This file contains all the files necessary for running the application. In Tomcat, all WAR files go under the webapps/ directory (in $CATALINA_HOME/ on Linux and %CATALINA_HOME%\ on Windows).
Once you have downloaded the opencms_5.0.1.zip file, unzip it to a temporary directory and copy the opencms.war file into Tomcat's webapps directory. While Tomcat will eventually automatically detect the new WAR file, 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 a directory ($CATALINA_HOME/webapps/opencms). By default, Tomcat unpacks WARs automatically, but other servlet containers may require additional configuration to elicit this behavior.
Configuring OpenCms to Use UTF-8
UTF-8 (Unicode), which supports multi-byte character encoding, is also supported in OpenCms. To use UTF-8, you will have to change the -Dfile.encoding=ISO-8859-1, set earlier in the Configuring Encoding section, to -Dfile.encoding=UTF-8. If you are running Windows and have already installed Tomcat as a service, you will need to uninstall the service and rerun the install script with UTF-8 in place of ISO-8859-1.
Also, you will need to edit the OpenCms properties file to set the correct encoding. Stop Tomcat and edit the opencms.properties file under $CATALINA_HOME/webapps/opencms/WEB_INF/. Find the line that reads:
Change ISO-8859-1 to UTF-8 and save the file.
It is possible to use other character sets, but if you do so, you may also have to configure the encoding that your database uses. Consult your database documentation to find out.
Verify that Tomcat is using the correct character encoding (see the Configuring Encoding section), and then start Tomcat again.
Running the Install Wizard
Once the opencms.war file is in place and Tomcat is restarted, you are ready to run the installer.
Note
Regarding browsers, 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 or may not work with other browsers.
Open a browser and enter the following URL to the OpenCms installer:
This will bring up the first screen of the OpenCms installation wizard. There are two installation modes: standard and advanced. Choosing the advanced mode will add three more screens of configurable details. Usually, the standard install is sufficient; however, for the sake of completeness, I'll go through the advanced setup.
Click on Continue to proceed to the database setup screen:
Set the User and Password fields for both Database Server Connection and OpenCms Connection to be the MySQL user created during MySQL setup. The rest of the fields should default to the correct values. Clicking on Continue will bring you to a page that warns that the existing opencms database will be dropped. Allowing the database to be dropped is fine as it contains nothing.
If everything on this screen says Ok, hit Continue. Failures during database installation usually indicate that the permissions for the MySQL user opencms were not set correctly. You can log in to the database and check the user by running a SELECT against the mysql.user table. Review the GRANT statements in the Finishing MySQL Setup section, and make sure that the user has the appropriate permissions.
The version-checking screen that follows will verify that all of the components are recognized. Since we are using the well-tested JDK 1.4/Tomcat/MySQL platform, things should check out here:
From this point, there are a few configuration screens that will show up only for the advanced setup mode. They provide an opportunity to tune parameters for caching, logging, and running. The first time you run the configuration, be cautious with changes to the advanced screens.
All of the parameters in these screens are written to the opencms.properties and registry.xml files, both of which are in $CATALINA_HOME/webapps/opencms/WEB-INF/config/. They can be changed after installation.
Advanced Setup Screens
If you are not running the advanced setup, which includes many options for configuring details of the system, you may prefer to skip to the Basic Setup Screens section.
Here is the first advanced screen:
Of note here is the database configuration section. If you are strapped for resources, lowering the minimum and maximum connections can boost performance. Also, if you are on a slow or overloaded machine, upping the timeout is a good idea. Usually, the defaults work fine.
Here are the details of the fields:
