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 -b master 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 Exit 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 -b master 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.

In other words: That's it.

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