<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd">
%CustomDTD;
]>
<chapter id="installation">
   <title>Installation Guide</title>
   <para>Starting with the 7.0 release Teiid needs to be installed into an 
   existing JBoss AS installation, which is entirely different from previous versions.
   <note>
   <para>Teiid does not support the "embedded" mode in &versionNumber; version. ("embedded" will be coming in a future release).</para>
   </note>
   </para>

   <section>
     <title>Installation</title>
     <orderedlist numeration="arabic">
     	<para>Steps to install Teiid</para>
        <listitem>
            <para>Download the <ulink url="http://www.jboss.org/jbossas/downloads.html">JBoss AS 7.1.0</ulink> application server. 
            Install the server by unzipping into a known location. Ex: /apps/jboss-7.1.0
            <note><para>You may also choose to use an existing AS installation.  However if a previous version of Teiid 
            was already installed, you must remove the old teiid distribution artifacts before installing the new version.</para>
            </note></para>
        </listitem>
        <listitem>
            <para>Download <ulink url="http://www.jboss.org/teiid/downloads.html">Teiid &versionNumber;</ulink>. 
            Unzip the downloaded artifact inside the JBoss AS installation. Teiid &versionNumber; directory structure matches 
            JBoss profiles directly - it is just an overlay. This will add necessary modules and configuration files to install Teiid
            in JBoss AS 7.x. Teiid works in both Standalone and Domain modes. Teiid provides separate configuration files 
            (standalone-teiid.xml and domain-teiid.xml) for both modes apart from the default configuration files come with JBoss AS 7.x
            </para>
            <para>The "Domain" mode recommended in a clustered environment to take advantage of clustered caching 
            and cluster safe distribution of events.</para>
        </listitem>
        
        <listitem>
        <para>Start the JBoss AS server by executing 
        <programlisting><![CDATA[
   <jboss-install>/bin/standalone.sh --server-config=standalone-teiid.xml
         ]]></programlisting>
        if you want to start the "standalone" profile. </para>
        
        <para>
        To start the server in "Domain" mode, install the JBoss AS 7.x and Teiid on all the servers in are going to be 
        part of the cluster. Select one of the server as the "master" domain controller, the rest of the 
        servers will be slaves that connect to the "master" domain controller for all the administrative operations. 
        Edit "host-teiid.xml" on all the slave servers in "jbossas/domain/configuration" directory, and make sure the 
        "domain-controller" element is configured with ip address of the "master" server. For example
        <programlisting><![CDATA[
     <domain-controller>
       <remote host="192.168.100.1" port="9999"/>
    </domain-controller>  
         ]]></programlisting>
         the port number is for the management interface, make sure they match to that of what you have in the configuration. 
         If you want to change the "server-group" name or add unique server names to each server then modify the "servers" element.
         Once all the configuration edits are done, then you can start JBoss AS in domain mode by executing the command         
        <programlisting><![CDATA[
   <jboss-install>/bin/domain.sh --domain-config=domain-teiid.xml --host-config=host-teiid.xml
         ]]></programlisting>
        on all the servers. Once all the servers are up, to complete the installion for the domain mode, 
        run the following command on any one server. Note that this only needs to be run for once per whole domain install. 
        Since in domain mode you can not statically deploy resources, this script deploys default resources required 
        (file, ldap, salesforce and ws connectors) for Teiid once the server starts using the CLI interface.
        <programlisting><![CDATA[
   <jboss-install>/bin/jboss-admin.sh --file=scripts/teiid-domain-mode-install.cli
         ]]></programlisting>
        </para> 
        </listitem>

        <listitem>
            <para>That it!. JBoss AS and Teiid are now installed and running.  See below instructions to customize various settings.</para> 
        </listitem>

        <listitem>
            <para>Once VDBs have been deployed, users can now connect their JDBC applications to Teiid. If you need help 
            on connecting your application to the Teiid using JDBC check out the "Client Developer's Guide".
        </para> 
        </listitem>        
     </orderedlist>
   </section>

   <section>
     <title>Directory Structure Explained</title>
     <example>
     <title>Directory Structure</title>
     <para>This shows the contents of the Teiid &versionNumber; deployment. The directory 
     structure is exactly the same under any JBoss profile.</para>
    <programlisting><![CDATA[
    /bin
        /scripts
	/docs
	   /teiid
            /datsources
            /schema
            /examples
   	/domain
	   /configuration
            domain-teiid.xml
	/modules
        /org/jboss/teiid/*
	/standalone
        /configuration
            standalone-teiid.xml
        /deployments
            teiid-*.rar
    ]]></programlisting>     
	</example>
    <section>
        <title>bin/scripts</title>
        <para>Has installation and utility CLI scripts.</para>
    </section>
    <section>
        <title>docs/teiid</title>
        <para>Has documents, examples, sample data source XML fragments and schema files. Contains artifacts 
        need by the Quick Start Example.</para>
    </section>

    <section>
        <title>/standalone/configuration/standalone-teiid.xml</title>
        <para>Master configuration file for Teiid system. This file contains Teiid subsystem in addtion to standard 
        JBoss AS web profile  subsystems</para>
    </section>
    
    <section>
        <title>/standalone/deployments</title>
        <para>This directory contains all the resource-adapter RAR files that are supplied as part of the Teiid installation. Note
        that resource adaptors are not installed by default for the domain mode. </para>
    </section>

    <section>
        <title>modules</title>
        <para>This directory defines the modules for JBoss As system</para>
    </section>
    
    <section>
        <title>/modules/org/jboss/teiid/main/conf</title>
        <itemizedlist>
        	<para>Relevant Files</para>
        	<listitem>
        		<para>/teiid-security-users.properties</para>	
        	</listitem>
        	<listitem>
        		<para>/teiid-security-roles.properties</para>	
        	</listitem>
        </itemizedlist>
        <para>These files define the allowed users and their defined roles in Teiid using the default security domain. Edit these 
        files to add uses. If you want to use a different security domain look for details in main configuration file.</para>
    </section>  
    
    <section>
        <title>/domain/configuration/domain-teiid.xml</title>
        <para>Master configuration file for Domain mode. This file contains Teiid subsystem in addtion to standard 
        JBoss AS web profile  subsystems.</para>
    </section>

    <section>
        <title>modules/org/jboss/teiid/client</title>
        <para>This directory contains Teiid client libraries. It has the Teiid JDBC driver jar, "teiid-&versionNumber;-client.jar", 
        and also contains "teiid-hibernate-dialect-&versionNumber;.jar" that contains Teiid's Hibernate dialect.</para>
    </section>
    
    <section>
        <title>{standlaone or domain}tmp/teiid</title>
        <para>This directory contains temporary files created by Teiid.  These are mostly created by the buffer manager.  
        These files are not needed across a VM restart.  Creation of Teiid lob values (for example through SQL/XML) will typically create one file per lob once it exceeds the allowable
        in memory size of 8KB.  In heavy usage scenarios, consider pointing the buffer directory at a partition that is routinely defragmented.
        </para>
    </section>
         
    <section>
        <title>{standlaone or domain}data/teiid-data</title>
        <para>This directory contains cached vdb metadata files. Do not edit them manually.
        </para>
    </section>         

   </section>   
   
</chapter>