Downloading Aspire with the Distribution Archetype

From wiki.searchtechnologies.com
Jump to: navigation, search

For Information on Aspire 3.1 Click Here

Use these instructions to download the Aspire software from the Search Technologies Maven repository, set up your first server running Aspire, launch Aspire, and install your first Aspire application using the System Administration interface.

You can install Aspire on any Windows or Linux machine which has an internet connection. Once installed, you can build distributsion to other servers without internet access, see Creating_Distributions_for_Machines_with_No_Internet_Access for more details.

Before you start the installation process, first make sure that you’ve taken care of any prerequisites. Also determine the following:

  • what port number Aspire should run on (it defaults to 50505, but you can change it if you wish)
  • what directory you want to install Aspire into

Then perform the following steps.


Step 1: Connect up to the Search Technologies Maven Repository

First, configure Maven locally so that it understands where the Search Technologies Maven Repository is located. (This is the internet location where all of the Aspire components are stored.) The URL is {{RepositoryUrl}. It is password protected; you will need to enter the same user name and password you used to access this wiki (i.e., your email address and a password of your choosing).


Once Maven understands where the ST repository is located, Maven can automatically download Aspire and all of its pieces to create new Aspire distributions with a single command.


Create the ".m2" directory in your user-name's home directory (if it does not already exist)

(IS THIS REQUIRED? May not be required for command-line Maven)

This is known as the "Maven Local Repository" and is the directory where Maven will store all of the components which it downloads onto your local machine.

  • On Windows XP: C:\Documents and Settings\{username}\.m2
  • On Windows 7: C:\Users\{username}\.m2

NOTE: Windows 7 may prevent you from creating this directory. It will say "You must type a file name." If this happens, you will need to create the directory using command-line tools:

  1. Open up a new DOS command-shell (go to the start menu, and enter "cmd" where it says "Run" or "Search for Programs", and then execute the cmd.exe program).
  2. Use "cd" to change directory to your user's home directory (the C:\Users\{username} directory)
  3. Enter: mkdir .m2

Create the settings.xml file inside your new ".m2" directory

The settings file can be found here: (link TBD)


Edit the settings file to include the actual values for the user name and password you used to register for the Aspire download.

<?xml version="1.0" encoding="UTF-8"?>
<settings>
 <servers>
   <server>
     <id>stPublic</id>
     <username>USERNAME</username>
     <password>PASSWORD</password>
   </server>
 </servers>

Step 2: Download the Aspire Maven Distribution Archetype

Now that Maven is configured locally, you need to download and install the Aspire Maven Distribution Archetype. What is a Maven Archetype? The purpose of a Maven archetype is to build a Maven “template” project. That template project can be used to create multiple new Maven projects or distributions. So basically, the sequence is:

Aspire Distribution Archetype --mvn--> Aspire Distribution Project --mvn--> Aspire Distribution

Why not just create a single distribution? Why create a Maven Project to create distributions?

In production systems there is never just one distribution. Most production systems have lots of different distributions:

  • Distributions for multiple machines in a large distributed system
  • A test or staging area
  • Development distributions
  • Distributions for individual developer machines

Using Maven profiles (see Introduction to Maven Profiles), it is possible to use a single Maven project to build all of these different types of distributions.


The Maven project built by the aspire-distribution-archetype is the starter project for this process. It can be used to create a single type of distribution, and then modified with Maven profiles to create distributions for all of the systems in your development, test, and production environments.


To download the aspire-distribution-archetype, do the following:

  1. Open up a DOS command window
  2. Use "cd" to change directory to someplace where you want to store the new Aspire distributions
  3. Execute the following command, exactly as shown, without modifying any of the parameters:
mvn archetype:generate -DarchetypeGroupId=com.searchtechnologies -DarchetypeArtifactId=aspire-distribution-archetype -DarchetypeVersion=0.5-SNAPSHOT -DrepositoryId=stPublic


Note that sometimes the "mvn" command will fail to locate the Search Technologies repository (it should be specified in your new settings.xml file). If this is a problem, then add the following argument to the "mvn" command from above:

-DarchetypeRepository=http://repository.searchtechnologies.com/artifactory/simple/community-public/


After executing the command, Maven will download a bunch of different Jar files. Most of these are various Maven plug-ins which Maven itself requires to execute. These plug-ins are downloaded automatically from the "master maven repository in the sky", namely http://repo.maven.apache.org.


Finally, once Maven itself is ready to go, you will be prompted for a "groupId", an "artifactId", and a "version".

Maven will prompt you for several input parameters:

Parameter Description
groupId The Maven group-id for your new distribution. It's usually the same as your organization's domain, but in reverse order, something like "com.searchtechnologies", or "com.your-company-name-here". It should be unique for your organization across all organizations in the world.
artifactId The Maven artifact-id for this project. This is the main Maven identifier for this distribution project, within the GroupID; typically something like "aspire-dev". Again, its purpose is to uniquely identify your distribution within your organization.
version The version number for your new distribution, such as "0.1-SNAPSHOT". The "-SNAPSHOT" is a Maven standard which means that this is a project which is currently in development. It can be removed once the project is officially "released".


Once you have entered all of the parameters, you will be prompted to verify your selections. Enter 'Y', and then Maven will create your new stage for you.


Once you have entered all of the parameters, you will be prompted to verify your selections. If you want to change the Port ID that Aspire will run on at this time, answer N and you will have the opportunity to change it (or any of the other parameters you entered); otherwise, enter 'Y', and then Maven will create your new distribution for you.


What you have created is a project for building various Aspire distributions. If you look at the directories and files created so far, you will see:

appBundle.xml distribution-files distribution.xml pom.xml


To see sample output of the mvn archetype:generate command you ran, click here (link TBD).

Step 3: Build Your Aspire Distribution

Next, you will need to execute Maven within your new distribution project to actually build your first distribution, as follows:

cd {distribution-name}
mvn clean package

Where {distribution-name} should be replaced with the distribution's "artifactId" that you entered above.


If you ever need to create a new distribution with fresh jars from the repository, then you would re-execute "mvn -U clean package" to get all of the latest code (for the revision numbers that are have specified in your pom.xml).


You should now have a ready-to-go Aspire distribution. A description of the directory structure can be found here: Aspire Directory Structure


Go to the next step to launch Aspire.

Step 4: Launch Aspire

The default Aspire distribution is a fully functional version of Aspire with a simple example configuration file. To start it up:

  1. Change your working directory to target\aspire-dev-0.1-SNAPSHOT-distribution (replacing “aspire-dev-0.1-SNAPSHOT” with whatever “artifactID” and “version” you entered above)
  2. Execute: bin\startup.bat

This will start up the Aspire servers. Aspire will take a minute or two to launch the first time because (just like Maven) Aspire will automatically download components from the Search Technologies Maven Repository. These are stored in the Maven local repository (the .m2 directory).


You should see something that looks like this:

> cd target\aspire-dev-0.1-SNAPSHOT-distribution
> bin\startup.bat
Removing Felix-Cache and AppBundle-Cache directories
-> Starting bundle: 9 - file:bundles/aspire/aspire-application-0.5-SNAPSHOT.jar
Settings (org.apache.felix.webconsole.internal.servlet.OsgiManager):  {password=admin, manager.root=/osgi, username=admin}
Started component factory: aspire-application (bundle 9)
.
.
.
Starting bundle: 13 - file:/C:/Users/pnelson/.m2/repository/com/searchtechnologies/aspire-extract-domain/0.5-SNAPSHOT/aspire- extract-domain-0.5-SNAPSHOT.jar
Started component factory: aspire-extract-domain (bundle 13)
Registering component: /FeedOneExample/StandardPipeManager/ExtractDomain
Registering component: /FeedOneExample/StandardPipeManager/PrintToFile
AUTOSTART: Complete


Once autostart is complete, go to the Aspire System Administration page, as described next.

Step 5: Access the Aspire System Administration Pages

The Aspire System Admin interface allows you to install and manage servers and content sources for Aspire. After launching Aspire (using bin\startup.bat), type the following URL into your browser:

http://localhost:50505/

(or if you changed the Port ID # during installation, substitute that port number for “50505”)


You should see a page that looks like this:

[add screenshot--image link TBD]