z2-Environment

h1. How to create your own system

This Wiki is on the task of creating a complete system of yours. I.e. to set up a development of your own solution based on the z2-base system.

*Note:* This is not needed to run the samples or to check things out. This is only useful, if you wish to start 

Fortunately, the actual things to do a are few and simple.

From a Z2 Core perspective it all starts with the local repository that is part of the core (to be found in @Z2_HOME/run/local@). In there, we define at least the _Base Repository_. The Base Repository typically points to some remote Git or Subversion based repository. Once Z2 has registered that repository, other repository may have appeared that will be registered as well which may lead to the appearance of more repositories and so on. Hence, in effect, we have a chain or tree of repositories with the local repository on its root as far as repositories contain declarations of repositories. 

On the other hand, repositories have a priority (more on that below) that determines what repository has the right to say what a module contains. 

Based on that mechanism you can construct a system definitions that consist of as few as one repository (if we do not count the core) or many repositories of which some are even shared between systems.

Before moving forward on that, let's have a look at the add-ons. 

h2. Add-ons

Add-ons (see [[Add-ons]]) add more functionality to Z2. Generally speaking, an add-on is a regular Git or Subversion  repository that holds one or more modules and is incorporated into a z2-Environment defined system via a component repository declaration (see Components and Component Repositories).

In other words, technically there is nothing particular about add-ons. It is the way they are used that is noteworthy. The idea is that you can pick the add-ons you need and add them on top of z2-base. Previously Z2 was available in distributions. Now you take z2-base and add what you need on top. 

Add-ons provided on z2-environment.net are versioned just like z2-base, so that there is no complicated version vector.  Also add-ons have some documentation in the z2-Environment Wiki and come with some samples.

h2. Assembling a system on z2-base and add-ons

Starting from a z2 core installation, a z2 home, there are two recommended repository configurations that hook a home up with remote content:

# com.zfabrik.boot.config/baseRepository (located in @<Z2_HOME>/run/local/com.zfabrik.boot.config/baseRepository.properties) and 

# com.zfabrik.boot.config/scenarioRepository (located in @<Z2_HOME>/run/local/com.zfabrik.boot.config/baseRepository.properties)

The first one points to the *z2-base.base* repository by default. The base repository completes the system to the extent that all commonly used features (such as the web container) are available. The second repository, the scenario repository, points to the top of the repository food chain that makes the solution (see the diagram below). This setup is of course a matter of choice and simply what we find practical. 

The scenario repository has a higher priority than the base repository, meaning that its module may overwrite definitions of the base repository.

Within the scenario repository (and, following the previous paragraph, as a fallback within the base repository), it is a best practice to encapsulate all system-specifc configuration in a module called *environment*. Also the repository "z2-base.base":http://redmine.z2-environment.net/projects/z2-base/repository/base contains an environment module (exactly "here":http://redmine.z2-environment.net/projects/z2-base/repository/base/show/environment?rev=master). 

The environment module is one of the preferred places to add additional repository definitions.

We recommend a setup where the z2-base repositories hosted z2-environment.net can be incorporated as-is, modulo copying or cloning, that has zero or more add-ons from z2-environment.net or from you and that has one scenario repository that assembles everything.

Such a setup consists of a *z2-base.core* (or a clone or a copy – in all cases from here on) and a *z2-base.base* plus zero or more add-ons, and one of possibly many scenario repositories.

The Local Repository, in the core, has the Base Repository pointing to *z2-base.base* and an Scenario Repository, next to the Base Repository (*z2-base.core* contains a template for that) that points to the Scenario Repository. 

The Scenario Repository has an *environment* module that has definitions for all other add-ons used in the scenario. 

And finally, the scenario component repository has a higher priority that the base component repository. 

Here is a schematic overview:

!extensions.png!

Sounds complicated. But in reality, it's really just filling the scenario component repository definition. The samples in z2-environment.net work almost exactly the same way. The difference is that we do not use the extension component repository but rather the Development Repository.

The effects of this setup are:

*The z2-base.core always stays connected with z2-base.base*

This is somewhat crucial. There is no meaningful way of using Z2 without a base repository like z2-base.base.

*You can run many scenarios with shared add-ons*

By only changing the scenario repository definition you can control a complete application system definition that is implemented on a Z2 Home - while still sharing all Add-on and base repositories. 

The *environment* module in the scenario repository defines what is part of the scenario.

*You can leave repositories from z2-environment.net untouched*

As you only re-use, typically you will not need to modify repository content unless you apply bug fixes and the like. That separates cleanly what is yours, what is from others.