Kick Start the z2-Environment Version 2.0:

What you will get:

  • A basic version of the Environment, the z2@base distribution that...
    • ...hosts Jetty (a popular Java Web Container)
    • ...hosts sample applications built on Hibernate, annotations, and module sharing
    • ...uses Git or Subversion as its versioned component store
  • An impression of how to install and distribute the z2 Environment
  • An impression of how to develop for the z2 Environment using Eclipse

Everything explained below should work on Windows, Linux and Mac OS X.

Before We Start...

The z2-Environment is available as Git repositories and from Subversion repositories. For the sake of this tutorial both approaches are described but you should only follow one at a time to keep things simple.

When using Git you get a complete baseline for further exploration by cloning our repositories from Gitorious.

When using Subversion, you can run and locally experiment just as well, but you do not have your own repositories as easily. Access to our repository is read-only. So, while you can modifiy and develop (as will be explained below), you will not be able to commit your changes to the repository. Later on you may decide to fill your own repository. Visit  Installation into your own repository to learn more about that.

(The distribution page z2@base, z2@spring provide more details on locations z2 is available from.)

You will need:

  • A Java Runtime Environment (greater or equal v1.6 a.k.a. Java 6)
  • A Subversion client or
  • Git

In both cases, if you want to see how development feels with the z2-Environment, you should also install the

  • Eclipse Integrated Development Environment.

Installing a Java Runtime Environment

Unless you already have a JRE of version 1.6 or higher installed, you should go to, download, and install one.

Installing Eclipse

You can get the Eclipse IDE from here. Please use a recent version (v3.5 or later will be ok), if you want to try our plugin. The Java Developer or the Java EE Developer edition will be sufficient.

Subclipse Users:

You will be able to find all necessary information on Subclipse, a Subversion client plugin for Eclipse here. If you know already how to do it, chose the Eclipse update site for installation. You can also find Subclipse in the Eclipse Marketplace (Help -> Eclipse Marketplace).

GIT Users:

We recommend using EGit, the Git client for Eclipse. Please install it from the Eclipse Marketplace  (Help -> Eclipse Marketplace).

Installing the z2 core

Now that the pre-requisites are fullfilled, we can install a z2 Home, an installation of a runtime of a system.

The nucleus of a z2 home is the core runtime: In order to connect to its versioned store and to bootstrap, the rarely changing core runtime of z2 needs to be present. To simplify things, it is best practice to keep the core runtime with all other modules that make the system in the versioned repositories.


Subversion Users:

In order to install it, we only need to "check it out".

Before however we will create a directory structure that can be used as a development workspace later on. So please create a folder workspace_z2_base, somewhere of your choice. If you are using Eclipse, create a workspace by that name.

In that folder, we will check out from the URL into a subfolder core using the user z2_base with password z2_base.

In Eclipse

Create a Subversion "Repository Location" (in the SVN Repository Exploring perspective) with the URL Right-click on core, choose "Checkout..." and subsequently "Check out as project in workspace". Everything should be filled out correctly already. Go.

From the Command Line

Open a Command Line window and change into the workspace folder you created. Type

svn co core

and hit enter.

Git Users:

Create a folder z2_base somewhere of your choice. We will create a directory structure that holds all repositories required as well as an Eclipse workspace. Fortunately this is almost completely automatic. Change into z2_base. Clone the core repository by running

git clone git://

Next change into core and check out the v2.0 branch:

git checkout v2.0

Finally run




(when on Windows). This script will clone further required repositories, namely base and samples from After completion, you will have three repository folders (core, base, and samples) and one workspace folder workspace next to each other.

Note: In a production setup, you would not need to have local clones of all system repositories. Instead, the z2 core can be configured to work with remote GIT repositories (of which it will maintain automatically pulled clones by itself).

That's it. You installed a z2-Environment home.

There will be no more installation or deployment as far as the z2-Environment is concerned - all other deployment will typically happen at the level of the repositories. Any update of a z2-Environment runtime consists of triggering a synchrnoization or,  in the more exceptional case, updating a "core" folder respectively.


Why is this important?

As far as the framework is concerned, horizontal scaling of a z2-Environment consists of no more than providing a Java SE and checking out from a Git or Subversion repository. There is no complex installation routine, all installation steps are non-proprietary. This makes scale out very economic.

As you will see later, almost anything that defines the actual system content, in terms of configuration and code is stored in a versioned repository, so that moving content between systems is a mere cross-repository transport. This allows for a very efficient operation of a development, test, and production landscape.

Proxy Settings

Important: If you are working in an intranet setup it may be required to specify proxy server configuration so that your z2 installation can reach our repositories (notable by an Exception at start up that indicates that our server name could not be resolved).

In that case, go to z2_base/run/bin and open the file  in a text editor (e.g. notepad on windows). Add the properties proxyHost and proxyPort (and if you have, proxyUser and proxyPassword - which is unlikely).

Your file should read similar to this afterwards (but please do NOT copy & paste this fragment! Only add the two properties mentioned (and substitute myproxyhost, myproxyport accordingly):

# alternative VM profiles for the home process
# VM opts
# default
    -Xms32M -Xmx32M -cp z.jar \
    -DproxyHost=myproxyhost -DproxyPort=myproxyport \ \ \
    -Dcom.zfabrik.home.concurrency=5 \
    -Dcom.zfabrik.home.layout=environment/home \
    -Dcom.zfabrik.home.autoVerifyInterval=600 \
    -Dcom.zfabrik.home.attainOperationTimeOut=300000 \ \
# override when -mode debug
home.vmopts.debug=-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,suspend=n,server=y,address=5000 -Dworker.debug=true

# override when -mode verbose
home.vmopts.verbose=-verbose:gc -XX:+PrintClassHistogram



Please continue with Starting.

Reading References