OpenCms is open source. It is shipped under GNU Lesser General Public Licence (LGPL) version 2.1 or later. So you are free to extend or modify it to adjust it to your requirements.

Development scenarios are different, and so are the recommended working environments. You may:

  • Only set up your website with OpenCms without adding extra Java-Code
  • Add extra modules to OpenCms that include your own classes / libraries
  • Extend, fix or alter the OpenCms core

Explore the topic to find out how to set up a suitable environment for your scenario.

What does "OpenCms development" mean?

When you set up a website with OpenCms you are already an OpenCms developer. You adjust OpenCms to the needs of your website, and add your own modules with templates and content types. But you may also dive deeper into the OpenCms internals. Here are three scenarios where you can work in as developer:

  • In the simplest scenario, you only use the predefined functionality, add your own templates and content types (or adjust the demo template and content).
  • In a more challenging scenario, you add extra Java code to your modules that handle special functionality of your website. So you extend OpenCms with your own functionality.
  • The last scenario is, that you work at the "cutting edge". You contribute to the OpenCms core and get your functionality shipped with the next OpenCms versionOf course, that assumes your functionality is selected for being added.

Dependent on your scenario, the development environment will differ. The next sections will give you an overview on recommended development environments.

Scenario: Writing own templates and formatters

You need nothing special here. Just install OpenCms locally and start developing. You can export your modules and place them on your webserver's OpenCms installation when development is done.

To make development more convenient, we recommend to mount the (offline version) of the VFS. That prevents you from site switching and allows you to use your favorit editor for writing JSPs and XSDs.

Scenario: Adding own Java code to your modules

Your Java code will typically use the OpenCms Java API. For development, we recommend the Eclipse IDE with Gradle for build automation. If configured correctly, gradle will automatically handle all dependencies of your code to the OpenCms core.

In the remainder of the section, we describe how to setup your own Eclipse project.

We assume you already have installed Eclipse and Gradle as described here.

3.1 Creating a project for your extensions

We recommend to create a Gradle project. This is done, choosing "File" -> "New" -> "Project" -> "Gradle project". Doing so, you get the following dialog:

When the project is created, adjust it as follows:

  • Delete the folders in the build path
  • Add folder src/ to the build path
  • Replace the content of build.gradle by (a variation of) the code shown below.
apply plugin: 'java'

sourceCompatibility = 1.6
targetCompatibility = 1.6
version = '1.0'

repositories {

    main {
        java.srcDir 'src'
        resources.srcDir 'src'

dependencies {
    compile group: 'org.opencms', name: 'opencms-core', version: '9.0.1'

jar {
    manifest {
        attributes 'Implementation-Title': 'OpenCms module', 'Implementation-Version': version

When you adjusted your project, refresh the dependencies. Therefor, right-click on your project and choose "Gradle" -> "Refresh Dependencies". This will add the OpenCms core as dependency to your project and thus available for development.

Refreshing dependencies may take some time since the new dependencies are downloaded.

3.1.1 Some background information about the Gradle configuration

OpenCms releases are available at http://mvnrepository.vom and Gradle grabs the dependencies from there. That's what you configure by

repositories { mavenCentral() }
dependencies { compile group: 'org.opencms', name: 'opencms-core', version: '9.0.1' }

Note that the core does not provide all modules usually provided by OpenCms. If you require further dependencies, search for them at the MVNrepository and copy the dependency string into your file.

3.2 Write code, compile and add it to OpenCms

We recommend to place your code in packages that are named as the module that the code is shipped with. It's a convention, not law, but useful. In the packages, just add classes as you like. When your setup is correct. You should have full access to the OpenCms API, can look in it's code and get auto-completion.

When it comes to compiling, choose "Run as" -> "External tools configurations ..." and select "Gradle Build". In the appearing dialog, you add a new configuration for your project and select the task "jar". It will compile all your classes and put them in a jar file when you run the configuration. The resulting jar is found in the subfolder /build/libs/ of your project's main folder.

To expose the library in OpenCms, copy it to the folder /WEB-INF/lib/ of your OpenCms' webapp home folder on the RFS. When you want to ship the jar with your module. Add it in the module's /lib/ subfolder in the VFS and set the export point for that folder to /WEB-INf/lib/.

3.3 Additional hints

It may be a good idea to use git, to control different versions of your code. Also, you may consider to place the whole module in your project and put it under version control. You'll still edit module resources in OpenCms, but export the module and place the (unzipped) export in a folder of your project.

Scenario: Working at the OpenCms core

The source code of OpenCms is available from a git repository hosted at GitHub. Depending on your focus you may

  • checkout the lates release and adjust it to your needs,
  • checkout the latest code and participate at the main development.

Depending on the scenario, you will check out the code differently, but otherwise, your working environment is set up similarly.

4.1 Check out the OpenCms source

4.1.1 Get the source for a release

To get the latest release, go to

 and choose the release, you want to manipulate. Then:

  • Download the source code
  • Extract the source code archive to the Eclipse workspace
  • Open Eclipse and add a new Java project where you use the name of the downloaded release as project name
  • Right-click on the project and select "Configure" -> "Convert to Gradle"
  • Refresh Gradle dependencies (dependency errors may remain, but are unproblematic)

4.1.2 Get the latest source

To check out the latest OpenCms version from GitHub via Eclipse, open Eclipse and:

  • Choose "File" -> "Import ..." -> "Git" -> "Projects from Git"
  • Click "Next" and select "Clone URI"
  • Set "" as URI and click "Next"
  • Select a branch and click "Next"
  • Select "Use the New Project wizard"
  • Uncheck "Use default location" and enter the repository's path as location
  • Click "Finish"

4.2 Core development configuration

Once, you got the OpenCms source and have it present in a Gradle project, you can configure:

  • the path were builds are placed: Therefore edit in the project's main folder and edit the entry build_directory.

Once, configuration is done, you can build your project with Gradle. Therefore:

  • Choose "Run as" -> "External tools configurations ..."
  • Choose "Gradle Build" -> "{project name}"
  • Choose adequate targets
  • Click "Run"

You will have a lot of target to choose for building OpenCms. Here are the interesting ones.

Interesting build targets

The target builds the .zip-archive as it is downloaded when getting the OpenCms release for installation.


The target builds the OpenCms updater.


The target builds the opencms.war file as deployed to the servlet container.

dist_{module name}

The target builds the .zip file for the respective module, as you use it for module import.

jar_{module name}

The target builds the Java library (.jar) for the specified module.


The target removes all build results, i.e., cleans up.

When you run a target, the created files are placed in subfolders of the configured build_directory. In particular:

  • libs/ contains .jar files
  • classes/ contains .class files
  • modulesZip/ contains .zip files of modules (as imported in OpenCms)
  • distributions/ contains files for distribution, i.e., opencms.war, opencms-{version}.zip,
  • ... the other folders are not so interesting.