z2-Environment

h1. How to Run a Sample

Various z2-based sample system configurations have been prepared as Git repositories. 

You can run these samples with very few manual steps in a local environment. This How-To describes what you need to do.

h2. 0. Pre-Requisites

All you need is Java Runtime Environment (JRE) of at least version 6. Preferrably, as that is easier to understand a sample, have the Eclipse IDE installed.

Other pre-requisites, for example some database setup may be required based on the specific example, i.e. stuff that cannot be covered here.

h2. 1. Prepare a z2-base Installation

Create a folder to hold the installation. We will assume that folder is called *sample*

In *sample* execute

<pre>

git clone http://git.z2-environment.net/z2-base.core

</pre>

Go into *sample/z2-base.core/run/bin* and run 

<pre>

./gui.sh

</pre>

or 

<pre>

gui.bat

</pre>

depending on your operating system. A simple graphical console should open up that displays the console log output of the z2 <home> and worker processes - as explained in http://www.z2-environment.eu/check_it_out.

At the first start, the environment will download required resources, which may take a few minutes - depending on your network bandwidth. Subsequent starts will be faster.

Eventually the server should be up and you can go to the basic admin view at http://localhost:8080/adm (use z* with password z) to verify everything is cool.

Stop the environment again by either pressing Ctrl+C on the console where you started the GUI or by clicking the Stop button on the GUI.

h2. 2. Clone the specific sample repository

Given the sample repository is called *z2-samples.sampleX*, go into *sample* once more and run 

<pre>

git clone http://git.z2-environment.net/z2-samples.sampleX

</pre>

Now start the environment as described above. The environment will now run with the sample configuration and all required dependencies.

h2. Why does that actually work

If you care, here is how everything falls into place:

The z2-base.core repository contains a z2 core installation that is bound to a remote "system repository" at http://git.z2-environment.net/z2-base.base. As it is by now best practice with z2, that repository contains an *environment* module that describes system specific settings such as other repositories.

By cloning the sample repository you put an override of *environment* module into view of the _dev repository_. That is, the local server will take your local definitions with preference over the remote definitions. These may include other remote component repositories such as *z2-addons.spring*.

In addition the sample repository contains all the modules holding code and other resources that implement the actual sample.

If you already understand how the _dev repository_ works, you will not be surprised to find files called LOCAL in the module folders of cloned repository's workspace.

h2. References

* Dev Repository: http://www.z2-environment.eu/v20doc#Workspace%20Development%20Using%20the%20Dev%20Repository