<commit_before># Installation

## Easy via a shell script


This project provides scripts to build TEAM Engine and the tests for Unix like systems
https://github.com/opengeospatial/teamengine-builder

## Downloading and building

### Getting the Source Code 

The source code is available from [GitHub](https://github.com/opengeospatial/teamengine). 
Use a Git client to clone the repository and checkout a branch or a tagged release 
as indicated below:

    git clone https://github.com/opengeospatial/teamengine.git
    git checkout ${project.version}

[Apache Maven 3](http://maven.apache.org/) is required to build the teamengine 
code base, which consists of the following modules:

-   **teamengine-core**: Main CTL script processor
-   **teamengine-resources**: Includes shared resources such as stylesheets
    and schemas
-   **teamengine-spi**: Provides an extensibility framework and a REST-like
    API for test execution
-   **teamengine-realm**: A custom Tomcat user realm
-   **teamengine-web**: A web application for executing test suites and
    browsing test results
-   **teamengine-console**: A console application that provides a
    command-line interface for executing test suites in Unix and Windows
    environments.

### Building with Maven

Simply run `mvn package` in the root project directory to generate all
build artifacts, or run `mvn install` to install them into the local
Maven repository. The main build artifacts are listed below.

- **teamengine-console-\${project.version}-bin.[zip|tar.gz]**: Archive containing the console application (command-line usage)
- **teamengine-console-\${project.version}-base.[zip|tar.gz]**: Archive containing the initial contents of the teamengine instance
    directory (TE\_BASE)
- **teamengine.war**: The JEE (Servlet) web application
- **teamengine-common-libs.[zip|tar.gz]**: Archive containing common runtime dependencies (e.g. JAX-RS 1.1,
    Apache Derby)

Alternatively, build the teamengine-web module and activate the
`ogc.cite` profile when doing so; this will automatically add all
supporting libraries to the WEB-INF/lib directory in the WAR file.
Specify the desired version of the ets-resources project in the
user-specific Maven settings file located at
`${user.home}/.m2/settings.xml`. See the [ets-resources project at
GitHub](https://github.com/opengeospatial/ets-resources) to determine
the latest version number (this is denoted by YY.MM.DD in the listing
below).

    <?xml version="1.0" encoding="UTF-8"?>
    <!-- ${user.home}/.m2/settings.xml -->
    <settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" 
      <!-- other elements omitted -->
      <profiles>
        <profile>
          <id>ogc.cite</id>
          <!-- Activate profile by default or using the -P option
          <activation>
            <activeByDefault>true</activeByDefault>
          </activation>
          -->
          <properties>
            <ets-resources-version>YY.MM.DD</ets-resources-version>
          </properties>
        </profile>
      </profiles>
    </settings>

A simpler alternative is to activate the profile and specify the
property using only command-line options:

    mvn package -P ogc.cite -Dets-resources-version=YY.MM.DD

The site documentation can be generated by simply executing the 'mvn
site' phase against the top-level POM. An aggregrate PDF document is
also created and placed in the target/pdf directory.


### Setting up an instance directory (TE_BASE)

The value of the `TE_BASE` system property or environment variable
specifies the location of the instance directory that contains several
essential sub-directories. Create the TE_BASE directory (e.g.
/srv/teamengine) and unpack the contents of the
teamengine-console-\${project.version}-base archive into this location;
make sure that users (including the Tomcat user) have write access. The
structure of the TE\_BASE directory is shown below.

    TE_BASE
      |-- config.xml    # main configuration file
      |-- resources/    # shared test suite resources
          |-- site      # site-specific HTML (welcome, title, etc.)
      |-- scripts/      # CTL test scripts
      |-- work/         # teamengine work directory
      +-- users/
         |-- {user1}/   # user account details and test run results
         |-- {user2}/
         +-- ...

CTL test scripts are placed in the TE_BASE/scripts directory. As a
convenience, the shell script `setup-tebase` is provided as part of the
[ets-resources](https://github.com/opengeospatial/ets-resources)
project; it may be run to initialize the instance directory with a set
of test suites specified in a CSV file. Note that in order to run the
script Maven and Git must be installed and available on the system path.

The location of a CSV file is passed as the first argument to the
script. Each line in the file should contain two fields: a Git
repository URL, and a tag name.

    https://github.com/opengeospatial/ets-gml32.git,1.21
    https://github.com/opengeospatial/ets-wfs20.git,1.19
    https://github.com/opengeospatial/ets-wfs11.git,1.24
    https://github.com/opengeospatial/ets-cat30.git,0.9
    ...

Running the script will populate the TE_BASE/scripts directory with the
listed test suites, add all required dependencies to
TE_BASE/resources/lib (for command line usage). See the [project
README](https://github.com/opengeospatial/ets-resources) for details.


### Deploying the web application

#### System requirements

-   Java runtime: Oracle JDK 8 - [latest JDK
    release](http://www.oracle.com/technetwork/java/javase/downloads/)
-   Servlet container: Apache Tomcat 7.0 - [latest Tomcat
    release](http://tomcat.apache.org/download-70.cgi)

#### Create a dedicated Tomcat instance

Apache Tomcat 7.0 is a supported servlet container. It is **strongly**
recommended that a dedicated Tomcat instance be created to host the
teamengine application. That is, keep the instance-specific
data--referred to as `CATALINA_BASE` in the Tomcat documentation--separate 
from the Tomcat software installation (CATALINA_HOME). Create it as 
outlined below for the applicable operating system.

To create a CATALINA_BASE directory in Windows:

    mkdir base-1 & cd base-1
    xcopy %CATALINA_HOME%\conf conf\
    mkdir lib logs temp webapps work

In a Unix-like environment:

    sudo mkdir -p /srv/tomcat/base-1; cd /srv/tomcat/base-1
    sudo cp -r $CATALINA_HOME/conf .
    sudo mkdir lib logs temp webapps work

The recommended JVM options for the Tomcat instance are shown below.
Note that the maximum memory heap size (`-Xmx`) may need to be increased
as the number of concurrent users increases.

`CATALINA_OPTS="-server -Xmx1024m -XX:MaxPermSize=128m -DTE_BASE=$TE_BASE -Dderby.system.home=$DERBY_DATA"`

Unpack the contents of the teamengine-common-libs archive into the
CATALINA_BASE/lib directory. Deploy the `teamengine.war` component by
either copying it into the CATALINA_BASE/webapps directory or using the
Tomcat *Manager* application. Start the Tomcat instance.

The URIs listed below provide starting points for discovering and
executing test suites. Modify the path if the name of the WAR file (and
hence the context path) has been changed from the default value
"teamengine".

* `/teamengine`: Home page for selecting and running CTL test suites
* `/teamengine/rest/suites`: Presents a listing of available (TestNG) test suites, 
with links to test suite documentation


### Customizing the welcome page

Several elements of the welcome page may be changed if desired: the logo
in the header, the main text, and the content in the footer. The files
located in the TE_BASE/resources/site directory can be modified to
provide site-specific content:


- **site/logo.png**: The logo that appears in the header (at top left). The size of the default image is 127x58 px.
- **site/welcome.txt**: The main text.
- **site/footer.txt**: Footer content.
- **site/title.html**: Title of the web application


An alias path must be added to the [web application context](https://tomcat.apache.org/tomcat-7.0-doc/config/context.html)
in order to make the site-specific content visible. Append the `/site` alias 
to the aliases attribute value in the META-INF/context.xml file as shown below. 
Reload the application (or restart Tomcat) to enable the new alias.

    <Context aliases="...,/site=${TE_BASE}/resources/site"><commit_msg>Added instructions about how to add a test manually in TEAM Engine.<commit_after># Installation

## Easy via a shell script

The [TEAM Engine Builder project](https://github.com/opengeospatial/teamengine-builder) provide a very easy way to build TEAM Engine and the tests. Script for Windows and Unix-like systems are available. Detailed instructions are provide in this tutorial.

## Downloading and building

### Getting the Source Code 

The source code is available from [GitHub](https://github.com/opengeospatial/teamengine). 
Use a Git client to clone the repository and checkout a branch or a tagged release 
as indicated below:

    git clone https://github.com/opengeospatial/teamengine.git
    git checkout ${project.version}

[Apache Maven 3](http://maven.apache.org/) is required to build the teamengine 
code base, which consists of the following modules:

-   **teamengine-core**: Main CTL script processor
-   **teamengine-resources**: Includes shared resources such as stylesheets
    and schemas
-   **teamengine-spi**: Provides an extensibility framework and a REST-like
    API for test execution
-   **teamengine-realm**: A custom Tomcat user realm
-   **teamengine-web**: A web application for executing test suites and
    browsing test results
-   **teamengine-console**: A console application that provides a
    command-line interface for executing test suites in Unix and Windows
    environments.

### Building with Maven

Simply run `mvn package` in the root project directory to generate all
build artifacts, or run `mvn install` to install them into the local
Maven repository. The main build artifacts are listed below.

- **teamengine-console-\${project.version}-bin.[zip|tar.gz]**: Archive containing the console application (command-line usage)
- **teamengine-console-\${project.version}-base.[zip|tar.gz]**: Archive containing the initial contents of the teamengine instance
    directory (TE\_BASE)
- **teamengine.war**: The JEE (Servlet) web application
- **teamengine-common-libs.[zip|tar.gz]**: Archive containing common runtime dependencies (e.g. JAX-RS 1.1,
    Apache Derby)

Alternatively, build the teamengine-web module and activate the
`ogc.cite` profile when doing so; this will automatically add all
supporting libraries to the WEB-INF/lib directory in the WAR file.
Specify the desired version of the ets-resources project in the
user-specific Maven settings file located at
`${user.home}/.m2/settings.xml`. See the [ets-resources project at
GitHub](https://github.com/opengeospatial/ets-resources) to determine
the latest version number (this is denoted by YY.MM.DD in the listing
below).

    <?xml version="1.0" encoding="UTF-8"?>
    <!-- ${user.home}/.m2/settings.xml -->
    <settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" 
      <!-- other elements omitted -->
      <profiles>
        <profile>
          <id>ogc.cite</id>
          <!-- Activate profile by default or using the -P option
          <activation>
            <activeByDefault>true</activeByDefault>
          </activation>
          -->
          <properties>
            <ets-resources-version>YY.MM.DD</ets-resources-version>
          </properties>
        </profile>
      </profiles>
    </settings>

A simpler alternative is to activate the profile and specify the
property using only command-line options:

    mvn package -P ogc.cite -Dets-resources-version=YY.MM.DD

The site documentation can be generated by simply executing the 'mvn
site' phase against the top-level POM. An aggregrate PDF document is
also created and placed in the target/pdf directory.


### Setting up an instance directory (TE_BASE)

The value of the `TE_BASE` system property or environment variable
specifies the location of the instance directory that contains several
essential sub-directories. Create the TE_BASE directory (e.g.
/srv/teamengine) and unpack the contents of the
teamengine-console-\${project.version}-base archive into this location;
make sure that users (including the Tomcat user) have write access. The
structure of the TE\_BASE directory is shown below.

    TE_BASE
      |-- config.xml    # main configuration file
      |-- resources/    # shared test suite resources
          |-- site      # site-specific HTML (welcome, title, etc.)
          |-- lib       # libraries required by some test (e.g. TestNG tests)
      |-- scripts/      # CTL test scripts
      |-- work/         # teamengine work directory
      +-- users/
         |-- {user1}/   # user account details and test run results
         |-- {user2}/
         +-- ...

CTL test scripts are placed in the TE_BASE/scripts directory. As a
convenience, the shell script `setup-tebase` is provided as part of the
[ets-resources](https://github.com/opengeospatial/ets-resources)
project; it may be run to initialize the instance directory with a set
of test suites specified in a CSV file. Note that in order to run the
script Maven and Git must be installed and available on the system path.

The location of a CSV file is passed as the first argument to the
script. Each line in the file should contain two fields: a Git
repository URL, and a tag name.

    https://github.com/opengeospatial/ets-gml32.git,1.21
    https://github.com/opengeospatial/ets-wfs20.git,1.19
    https://github.com/opengeospatial/ets-wfs11.git,1.24
    https://github.com/opengeospatial/ets-cat30.git,0.9
    ...

Running the script will populate the TE_BASE/scripts directory with the
listed test suites, add all required dependencies to
TE_BASE/resources/lib (for command line usage). See the [project
README](https://github.com/opengeospatial/ets-resources) for details.


### Deploying the web application

#### System requirements

-   Java runtime: Oracle JDK 8 - [latest JDK
    release](http://www.oracle.com/technetwork/java/javase/downloads/)
-   Servlet container: Apache Tomcat 7.0 - [latest Tomcat
    release](http://tomcat.apache.org/download-70.cgi)

#### Create a dedicated Tomcat instance

Apache Tomcat 7.0 is a supported servlet container. It is **strongly**
recommended that a dedicated Tomcat instance be created to host the
teamengine application. That is, keep the instance-specific
data--referred to as `CATALINA_BASE` in the Tomcat documentation--separate 
from the Tomcat software installation (CATALINA_HOME). Create it as 
outlined below for the applicable operating system.

To create a CATALINA_BASE directory in Windows:

    mkdir base-1 & cd base-1
    xcopy %CATALINA_HOME%\conf conf\
    mkdir lib logs temp webapps work

In a Unix-like environment:

    sudo mkdir -p /srv/tomcat/base-1; cd /srv/tomcat/base-1
    sudo cp -r $CATALINA_HOME/conf .
    sudo mkdir lib logs temp webapps work

The recommended JVM options for the Tomcat instance are shown below.
Note that the maximum memory heap size (`-Xmx`) may need to be increased
as the number of concurrent users increases.

`CATALINA_OPTS="-server -Xmx1024m -XX:MaxPermSize=128m -DTE_BASE=$TE_BASE -Dderby.system.home=$DERBY_DATA"`

Unpack the contents of the teamengine-common-libs archive into the
CATALINA_BASE/lib directory. Deploy the `teamengine.war` component by
either copying it into the CATALINA_BASE/webapps directory or using the
Tomcat *Manager* application. Start the Tomcat instance.

The URIs listed below provide starting points for discovering and
executing test suites. Modify the path if the name of the WAR file (and
hence the context path) has been changed from the default value
"teamengine".

* `/teamengine`: Home page for selecting and running CTL test suites
* `/teamengine/rest/suites`: Presents a listing of available (TestNG) test suites, 
with links to test suite documentation


### Installations of tests in TEAM ENGINE

There are various examples of tests that can be installed in TEAM Engine. For example.

- [GML 3.2.1](https://github.com/opengeospatial/ets-gml32)
- [WMS 1.3](https://github.com/opengeospatial/ets-wms13)

Even though the first one uses TestNG and the second uses CTL, they both follow maven best practice conventions and are build and treated the same way when installing them in TEAM Engine. To download and install a test do the following steps:

1. checkout the test repository: e.g. `git clone  https://github.com/opengeospatial/ets-gml32.git`
2. go inside the project" `cd ets-gml32`
3. checkout a specific version. e.g. for 1.23 `git checkout 1.123`
4. build using maven `mvn clean install`
5. check that the build is succesful. You should see a **BUILD SUCCESS** text in the terminal
6. go to the target folder `cd target`
7. unzip the file that ends with *ctl.zip* to $TE_BASE/scripts
8. unzip the file that ends with *deps.zip* to $TE_BASE/resources/lib, to run in command line
9. unzip the file that ends with *deps.zip* to the web app library. If teamngine was installed as teamengine in tomcat, then the libraies in deps.zip should be copied under webapps/teamengine/WEB-INF/lib 


### Customizing the welcome page

Several elements of the welcome page may be changed if desired: the logo
in the header, the main text, and the content in the footer. The files
located in the TE_BASE/resources/site directory can be modified to
provide site-specific content:


- **site/logo.png**: The logo that appears in the header (at top left). The size of the default image is 127x58 px.
- **site/welcome.txt**: The main text.
- **site/footer.txt**: Footer content.
- **site/title.html**: Title of the web application


An alias path must be added to the [web application context](https://tomcat.apache.org/tomcat-7.0-doc/config/context.html)
in order to make the site-specific content visible. Append the `/site` alias 
to the aliases attribute value in the META-INF/context.xml file as shown below. 
Reload the application (or restart Tomcat) to enable the new alias.

    <Context aliases="...,/site=${TE_BASE}/resources/site">
{'fraction_non_alphanumeric': 0.08791570628910109, 'fraction_numerical': 0.007847656678739984, 'mean_word_length': 3.6629989764585464, 'pattern_counts': {'":': 0, '<': 45, '<?xml version=': 2, '>': 43, 'https://': 25, 'lorem ipsum': 0, 'www.': 2, 'xml': 12}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 7, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1344895', 'n_tokens_mistral': 5282, 'n_tokens_neox': 4993, 'n_words': 2146}