Setting up OpenCms
OpenCms-Maven is basically a Maven Plug-in that enables synchronization between OpenCms VFS resources and a real file system. This enables full automated builds of OpenCms from scratch from one defined repository. VFS contents can be versioned as human readable text files so all the benefits of a version control system can be used, including concurrent versioning, conflict management etc. There's no need anymore to put binary data like db-dumps into your versioning control system.
Until OpenCms 7 some modifications of OpenCms were necessary to enable OpenCms to work with Maven. Since OpenCms 7.5 this is no longer the case. We now use the opencms.jar which is shipped with standard OpenCms.
In order to be able to build a OpenCms from scratch, we created a OpenCms distribution which is already prepared for being built with Maven. This distribution is called opencms-basic which enables to build a runnable OpenCms system with only basic modules and extensions. The opencms-basic project can be used as a starting point to create customized OpenCms installations.
To use the OpenCms-Maven tool you must have the following software installed:
- JSE >= 1.4
- Apache Tomcat >= 5.x
- MySQL or PostgreSQL database
- Client, to access your version control system (SVN, GIT etc.)
- Eclipse IDE (optional but recommended)
Also you need an Internet connection that allows http and https requests by the maven executable.
To install Maven 2 or 3 just download the distribution from the Maven homepage the and extract it to a directory of your choice. For convenience you should then add the bin subdirectory of the extracted Maven directory to your PATH environment variable. For Unix like systems you can also look if Maven is supported by your distribution and use a package manager to install it.
To test if the Maven executable can be found, open a new command line interface and type mvn . You should then get a Maven error message that no parameters have been passed.
Maven creates an own directory in the user's home path to store its configuration. By default this will be <user's_home_directory>/.m2 on both Linux and Windows systems. If you've already run the Maven executable this directory should have been created automatically. If it doesn't exist you can also create it manually.
Get latest version of OpenCms basic
When you've checked out / downloaded the project you have to adjust some settings within the so called parent POM which is located at parent/pom.xml.
The interesting part of the parent POM is the <properties> section:
Here you can set your db connection to use for the OpenCms installation and the place of the OpenCms logfile which by default will be the root directoy of the drive where the servlet container runs.
Caution: Because the opencms-basic project is just connected to Git at the OpenCms-Maven project site you won't be able to commit changes to it. The opencms-basic project is just a basic installation that can be used as a basis for further modification. So you have to copy or relocate the whole opencms-basic installation to your own repository if you wan't to modify it and commit changes.
Building the OpenCms installation
Maven uses so called phases within its build life cycle. The interesting phases for OpenCms-Maven projects are
The clean phase drops all existing tables in the database that you defined within the parent POM. The package phase triggers the actual build process. All phases have to be called from the directory that contains the parent POM. To call the phases you have to open a command line and type mvn <phasename>. To build the Maven installation type the following within the parent directory:
Every phase should be finished with a build successfull message. When you call Maven the first time it may take some time because the dependent artifacts have to be downloaded from the internet.
Deploying OpenCms to Tomcat
If the package phase completed successfully Maven is ready to install. Therefore a special Maven plugin will be used. To set the context name of the OpenCms webapp you can set the path property of the plugin's configuration section within the parent POM:
Example of the tomcat configuration in your parent POM:
By default port 8080 and a tomcat user called admin who doesn't have a password set is used for deployment. If the user doesn't exist edit your tomcat-users.xml and add the following line:
<user roles="manager-script" password="" username="admin" />
(If you want to use different settings have a look at the tomcat plugin website.)
Now the project is ready to be actually deployed to Tomcat. To do this, start Tomcat on port 8080 and type the following command within the parent directory:
The OpenCms installation should instantly be deployed to your tomcat server.