See also...

Hippo Baby Steps 

This document describes how to get started with Hippo CMS 7. This includes building the content management module (CMS), a content repository initialisation module and the HST-based site application. The Hippo Site Toolkit (HST) is a toolkit for developing content based Java Web Applications using the Hippo CMS stack. This page helps you get the CMS and a sample web application up and running with your own HST-2 based project as quickly as possible.

The preferred way to start a Hippo CMS 7 project is to use the HST archetype to generate a Maven project. You need to have Java 6 or 7 and Maven version 3+ is needed. This page also assumes that you have some basic knowledge on how to use Maven. Make sure your Maven installation works properly and that if you are on Windows you don't have spaces in either your Maven installation path or the path to your local Maven repository. 

Creating a project

Maven archetypes are templates of projects. Maven can generate a new project from such a template. For a project using the HST, you need the website archetype. In the folder in which the new project folder should be created, type the command shown below. On Windows, run the command on a single line and leave out the line continuation characters ('\'). 

mvn archetype:generate \
-DarchetypeRepository=http://maven.onehippo.com/maven2 \
-DarchetypeGroupId=org.onehippo.cms7 \
-DarchetypeArtifactId=hippo-archetype-website \
-DarchetypeVersion=1.07.02
If you're behind a proxy, you need to have the right settings applied in your Maven configuration file. See the Maven guide to using proxies on how to do that.

We make an effort to keep this page up to date with the latest stable archetype version. You can always check for the latest archetype here:

http://maven.onehippo.com/maven2/org/onehippo/cms7/archetypes/

The archetypes for Hippo CMS 7.8 are in the 1.07.xx range. The latest micro version of that range is the one you will want to use.

All archetype tags can be found at:

http://svn.onehippo.org/repos/hippo/hippo-cms7/archetypes/tags/

This list contains official as well as unofficial releases and release candidates. Release candidates will not be released, only tagged, so if you want to use one, you have to build it yourself.

The archetype is configured with default values for all properties required by the archetype. If you want to customize any of these property values, type 'n' when prompted for confirmation.

You will be asked for:

  1. the groupId, (something like 'com.mycompany')
  2. the artifactId (something like 'myproject')
  3. the version number (you can use the default, it is good practice to have 'SNAPSHOT' in the version number during development and the maven release plugin makes use of that string. But ensure to comply to the desired numbering scheme for your project. E.g. Hippo CMS and HST version numbers have 1.01.00 format).
  4. the package name. This is the java package name. A folder structure according to this name will be generated automatically. Use the default, which is equal to the groupId.
  5. the project name (something like 'My Project')

Maven will create a project for you (in a newly created directory named after the value of the artifactId property you specified ) containing 3 subprojects:

  • cms - a pre-configured content repository and CMS
  • bootstrap - configuration and sample content including a document type and some documents for the sample site
  • site - a sample HST-2 based Java Web Application

Now build your project using the following command in the root folder of your project: 

mvn install

This will produce two WAR files and two JAR files:

  • cms/target/cms.war
  • site/target/site.war
  • bootstrap/configuration/target/myproject-bootstrap-configuration-1.01.00-SNAPSHOT.jar
  • bootstrap/content/target/myproject-bootstrap-content-1.01.00-SNAPSHOT.jar

The CMS WAR module has dependencies on the bootstrap-configuration and bootstrap-content modules so that the respective JARs are packaged with the CMS WAR. When the CMS web application is started up for the first time the configuration settings and sample content from the JAR files are then loaded into the repository.

You are now ready to run your project.

Running a project

For a fast development cycle, you can run both the CMS/Repository and the website from the command lines using Cargo. Cargo is a Java EE container management tool that we use from Maven to start and deploy web applications in Tomcat. To learn more about Cargo and its use by Hippo projects refer Run and develop with Cargo.

To run the CMS and sample website, issue the following command from the root directory: 

mvn -P cargo.run

If you do not want to have your repository, possibly with changes, flushed after a new mvn clean install you can specify to store the repository content in a different location. You can do this from the command line as follows: 

mvn -P cargo.run -Drepo.path=/home/usr/myrepo

Add -Drepo.path=/home/usr/myrepo to the mvn command if you want to keep your repository during mvn clean install

Notice

In case one of the above lines fail due to the following exception:

Execution cargo-run of goal org.codehaus.cargo:cargo-maven2-plugin:1.1.1:run failed: Failed to download http://apache.hippo.nl/tomcat/tomcat-6/v6.0.32/bin/apache-tomcat-6.0.32.tar.gz:

You will need to update the parent pom of the generated project to specifically specify the latest stable version of Apache Tomcat. You can do this by adding the following property within the properties section of the maven pom.xml file: 

<cargo.tomcat.full.version>6.0.35</cargo.tomcat.full.version>

Hippo CMS 7 is now available at http://localhost:8080/cms/ . Also, at http://localhost:8080/cms/console you can reach the CMS console. The console is a front end to the JCR repository that Hippo uses as its back end. You can use it to manage all system configuration and content. Username and password for logging in to the cms and the console are admin/admin.

If you want the changes you make to the repository through the cms or console to be exported to your local bootstrap xml content files, take a look at Automatic export.

To view the sample website open http://localhost:8080/site/.

Finally the logs for the website and the CMS can be found at: 

target/tomcat6x/logs/hippo-site.log
target/tomcat6x/logs/hippo-cms.log

Working with an IDE

Since Hippo CMS 7 is a Maven based project, you can open it and run it using almost any IDE you wish. Importing a Maven project into an IDE is quite straightforward and, depending on the IDE you choose, can really speed up your development, maintenance and testing procedures. At the time of this writing you can find up to date instructions on opening, running and debugging Hippo CMS 7 from within Eclipse or IntelliJ:

Where to go next

Start experimenting with your fresh installation. Continue with Grazing Hippo to learn how you can use CMS 7 to build a real site in less than a day!