For more information on Aspire Distributions, see also this page: Using The Maven Distribution Archetype
The previous quick-start used a pre-built Aspire distribution which was fixed for a certain set of components.
In this quick-start, you'll learn how to build an Aspire distribution from scratch, using the Aspire Maven Distribution archetype. Also, all of the components will be automatically downloaded from Maven repositories - making system configuration and deployment a breeze.
Prerequisites
Before you begin, you need to be registered to use Aspire (go to http://aspire.searchtechnologies.com/) if you haven't already done that.
You will need your user registration name and password in order to complete this tutorial.
Step 4: Use Maven to Create a New Aspire Distribution
More detailed documentation for creating new distributions is here: Using The Maven Distribution Archetype
Now that Maven is installed, creating a new Aspire distribution is relatively easy. Our recommendations are to:
- Open up a DOS command window (see step 1 for instructions).
- Use "cd" to change the directory to someplace where you want to store the new Aspire distributions.
- Execute the command shown below.
mvn archetype:generate -DarchetypeGroupId=com.searchtechnologies.aspire -DarchetypeArtifactId=aspire-distribution-archetype -DarchetypeVersion=2.2.2 -DrepositoryId=stPublic
The command should be executed exactly as is. Do not modify the parameters (they specify where to locate the instructions for how to build a new Aspire Distribution).
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, 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 the following information:
- groupId - This is the name of the organizational unit to which your distribution belongs. It's usually the same as your organization domain but in reverse order (for example, "com.searchtechnologies.aspire"). If the distribution belongs to a customer, you should use that customer's groupId.
- The purpose of the groupId is to distinguish this distribution from all other maven distributions built by other organizations throughout the world (just in case somebody somewhere wants to re-use your distribution someday).
- artifactId - This is the name for your distribution. Technically, it should be unique name across all distributions (or any other maven project) within the organization specified by groupId. Again, it's purpose is to uniquely identify your distribution within your organization.
- version - This will be the version number for this distribution.
- I usually use "0.1-SNAPSHOT".
- I say "0.1" to not be presumptuous. In other words, projects that are just starting out should start at 0.1, until they get tested and used at least a little bit.
- 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".
- mavenPassword - This will be the Maven password you got when you registered.
- mavenUsername - This will be the Maven username which you got when you registered.
After you enter the final information and press the Enter key, you are prompted to confirm the entered information. Enter Y and press the Enter key again.
Here is an example output:
>mvn archetype:generate -DarchetypeGroupId=com.searchtechnologies.aspire -DarchetypeArtifactId=aspire-distribution-archetype -DarchetypeVersion=2.2.2 -DrepositoryId=stPublic [INFO] Scanning for projects... Downloading: http://repo.maven.apache.org/maven2/org/apache/maven/plugins/maven-clean-plugin/2.4.1/maven-clean-plugin-2.4.1.pom . . . Define value for property 'groupId': : com.searchtechnologies Define value for property 'artifactId': : aspire-demo Define value for property 'version': 1.0-SNAPSHOT: : 0.1-SNAPSHOT Define value for property 'mavenPassword': : : xxx Define value for property 'mavenUsername': : : [email protected] [INFO] Using property: package = pom Confirm properties configuration: groupId: com.searchtechnologies artifactId: aspire-demo version: 0.1-SNAPSHOT package: pom Y: : y [INFO] ---------------------------------------------------------------------------- [INFO] Using following parameters for creating project from Archetype: aspire-distribution-archetype:2.2.2 [INFO] ---------------------------------------------------------------------------- [INFO] Parameter: groupId, Value: com.searchtechnologies [INFO] Parameter: artifactId, Value: aspire-demo [INFO] Parameter: version, Value: 0.1-SNAPSHOT [INFO] Parameter: package, Value: pom [INFO] Parameter: packageInPathFormat, Value: pom [INFO] Parameter: version, Value: 0.1-SNAPSHOT [INFO] Parameter: package, Value: pom [INFO] Parameter: groupId, Value: com.searchtechnologies [INFO] Parameter: artifactId, Value: aspire-demo [INFO] Parameter: mavenPassword, Value: xxx [INFO] Parameter: mavenUsername, Value: [email protected] [INFO] project created from Archetype in dir: C:\Users\pnelson\Desktop\AspireDemo\aspire-demo [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 45.292s [INFO] Finished at: Wed Jan 26 13:28:55 EST 2014 [INFO] Final Memory: 9M/109M [INFO] ------------------------------------------------------------------------
Step 5: Build the Distribution
So now you can run Aspire, right? Well, actually, there's one more step.
The purpose of the Maven archetype (the previous step) was to build a Maven distribution project. Essentially this is a template distribution. We will now need to use Maven to build the distribution itself.
The sequence goes like this:
Aspire Distribution Archetype --mvn--> Aspire Distribution Project --mvn--> Aspire Distribution
Why is it so complicated? Well, Aspire is meant for industrial-strength production installations. It is not a toy system. This means:
- There needs to be a solid, repeatable method for building deployments.
- The same distribution will likely need to be built for multiple environments:
- Development
- Quality Assurance
- Staging
- Production
The Maven Distribution Project amply fulfills these needs. It provides a template for building copies of your distribution. Maven "profiles" can be used to customize the template for different environments, specifying different server addresses and database names for the Development environment vs the Staging environment, for example.
Okay, so let's actually build our Aspire distribution. Fortunately, this is very easy.
- Change your working directory into your Maven distribution project; this is the same as what you entered in step 5 for the artifactId.
- In the command window, execute: mvn clean package
Again, since this is your first time executing "mvnpackage", Maven will download a bunch of plug-ins, which it needs to do its job. But once that's done, it will build the Aspire distribution and you're ready to go.
> cd aspire-demo > mvn clean package [INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building Aspire Distribution Project 0.1-SNAPSHOT [INFO] ------------------------------------------------------------------------ Downloading: http://repo.maven.apache.org/maven2/org/apache/maven/plugins/maven-resources-plugin/2.5/maven-resources plugin-2.5.pom Downloaded: http://repo.maven.apache.org/maven2/org/apache/maven/plugins/maven-resources-plugin/2.5/maven-resources plugin-2.5.pom (7 KB at 15.1 KB/se c) Downloading: http://repo.maven.apache.org/maven2/org/apache/maven/plugins/maven-plugins/19/maven-plugins-19.pom . . . [INFO] Reading assembly descriptor: distribution.xml [INFO] Copying files to C:\Users\pnelson\Desktop\AspireDemo\aspire-demo\target\aspire-demo-0.1-SNAPSHOT-distribution [WARNING] Assembly file: C:\Users\pnelson\Desktop\AspireDemo\aspire-demo\target\aspire-demo-0.1-SNAPSHOT-distribution is not a regular file (it may be a directory). It cannot be attached to the project build for installation or deployment. [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 3:12.857s [INFO] Finished at: Wed Jan 25 13:46:04 EST 2012 [INFO] Final Memory: 9M/51M [INFO] ------------------------------------------------------------------------
Messages you could see when building the distribution
There are a number of warning message you may see when building the distribution. Don't let this worry you. Basically, if you see the following message, everything worked OK :
[INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------
However, here's an explanation of warnings you may see.
This warning refers to the fact we don’t hardcode the encoding for the ASCII files we use. We tried to do this in the very early stages and it gave us more problems than it fixed. This shouldn’t cause any issues as long as you’re not working in any languages that use extended character sets.
[WARNING] Using platform encoding (MacRoman actually) to copy filtered resources, i.e. build is platform dependent!
We recently changed the build process so that you could include dependencies in the pom file to cause “application bundles” to be copied from Maven into the target bundles/aspire directory at build time. This allows Aspire to use those application bundles on hosts which have no internet access. You've always been able to do that with component bundles. The message below tells you that you’ve not got any dependencies with the group id com.searchtechnologies.appbundles.
[WARNING] The following patterns were never triggered in this artifact inclusion filter: o 'com.searchtechnologies.appbundles:*'
Some versions of Maven's mvncommand(mainly 2.x) produce an unwanted file and copy it to the target bundles/aspire directory. This warning indicates your version didn’t (as this line warns you the file is not being excluded when things are being copied to the target directory)
[WARNING] The following patterns were never triggered in this artifact exclusion filter: o 'com.searchtools:aspire-demo:jar:0.3-SNAPSHOT'
This warning just refers to the fact that the build is copying to a directory and therefore can not produce something that can be placed back in a Maven repository.
[WARNING] Assembly file: /Users/st/aspire-test-3/aspire-demo/target/aspire-demo-0.3-SNAPSHOT-distribution is not a regular file (it may be a directory). It cannot be attached to the project build for installation or deployment.
mvn install
In Maven 2.x, you can get away with running the following command to build the distribution:
mvn install
In Maven 3.x, you can't run this command to build a distribution, so make sure you use mvn package as detailed above. If you do use install, the build will fail and you'll see the following:
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-install-plugin:2.3.1:install (default-install) on project test-project: The packaging for this project did not assign a file to the build artifact -> [Help 1] [ERROR] [ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch. [ERROR] Re-run Maven using the -X switch to enable full debug logging. [ERROR] [ERROR] For more information about the errors and possible solutions, please read the following articles: [ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException
Step 6: Launch Default Distribution
The default Aspire distribution is a fully functional version of Aspire. Let's launch Aspire.
- In the command window, change your working directoryto:target\aspire-demo-0.1-SNAPSHOT-distribution
- Execute: bin\startup.bat
Here is example output:
Removing Felix-Cache and AppBundle-Cache directories ************************************************************************ * * ASPIRE BOOTLOADER * * Bundle id : 10 * * Location : file:bundles/boot/aspire-bootloader-2.2.2.jar * . . . . 2014-02-04T20:38:43Z INFO [/Workflow]: Installed component: /Workflow/WfManager 2014-02-04T20:38:43Z INFO [aspire]: Successfully started appBundle: /Workflow (location: com.searchtechnologies.aspire:app-workflow-manager) AUTOSTART: No applications to start
NOTE: If you are downloading Aspire Community, ignore the error message about being unable to download the com.searchtechnologies.aspire:aspire-dcm-enterprise component. The aspire-dcm-enterprise component is available only with Enterprise systems (and is used for Distributed Processing and Failover).
At this point, you can use the standard administration interface (http://localhost:50505) to install pre-packaged applications such as connectors and search engine publishers. Go to UI Introduction for more details.
Errors?
If you see an error like this:
2014-11-19T10:20:35Z INFO [BOOTLOADER]: Fetching: com.searchtechnologies.aspire:aspire-application:2.0.3 2014-11-19T10:20:43Z ERROR [BOOTLOADER]: Cannot get file from repository (http://repository.searchtechnologies.com/artifactory/simple/community-public/) - check the component is properly deployed. File: http://repository.searchtechnologies.com/artifactory/simple/community-public/com/searchtechnologies/aspire/aspire-application/2.0.3/aspire-application-2.0.3.jar org.apache.maven.wagon.authorization.AuthorizationException: Access denied to: http://repository.searchtechnologies.com/artifactory/simple/community-public/com/searchtechnologies/aspire/aspire-application/2.0.3/aspire-application-2.0.3.jar at org.apache.maven.wagon.providers.http.LightweightHttpWagon.fillInputData(LightweightHttpWagon.java:119) at org.apache.maven.wagon.StreamWagon.getInputStream(StreamWagon.java:116) at org.apache.maven.wagon.StreamWagon.getIfNewer(StreamWagon.java:88) at org.apache.maven.wagon.StreamWagon.get(StreamWagon.java:61) at org.sonatype.aether.connector.wagon.WagonRepositoryConnector$GetTask.run(WagonRepositoryConnector.java:511) at java.util.concurrent.ThreadPoolExecutor$Worker.runTask(ThreadPoolExecutor.java:895) at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:918) at java.lang.Thread.run(Thread.java:662)
and Aspire exits:
ERROR: Failed to load Aspire application Shutting down OSGI
the first thing to check is that you have the correct username and password in the config/settings.xml file. See here for details.
Step 9: Congratulations!! And Where to Go From Here?
Congratulations! You have built a brand-new distribution of Aspire from scratch using the distribution archetype, and you launched the default Aspire installation and processed a URL. Cool!
Here are some suggestions on what to do next:
- Explore your distribution. Especially look into the config directory and read the "settings.xml" and "application.xml" files.
- For more information on the settings.xml file, go here: Settings Configuration
- For more information on the application.xml file, go here: Application Configuration.
- Try adding a Groovy Scripting stage to your component.
- Groovy scripting allows you to print/read/modify the metadata for documents processed by Aspire. It is the most common way to add custom processing to an Aspire pipeline.
- More information on Groovy Scripting with Aspire can be found here: Using Groovy
- Note that you'll need to add your new Groovy Scripting component to your Aspire pipeline. See here: Pipeline Manager to learn more about pipelines
For example, the following is a minimal Groovy Scripting component:
<component name="SampleGroovyScript" subType="default" factoryName="aspire-groovy"> <config> <script> <![CDATA[ println "Hello World!"; println "The Aspire Document is this: "; println doc.toString(/*pretty:*/true); ]]> </script> </config> </component>
You can add this component to your default Aspire configuration using the following steps:
- Add the component to your "application.xml" file.
- Put it after the <component name="ExtractDomain"> component
- Then add "SampleGroovyScript" as a stage to your pipeline.
- Put it after <stage component="ExtractDomain" />
- Now reload your configuration
- Do this by going to Aspire debug console home: http://localhost:50505/aspire
- Then click on the circular arrow button next to the "/FeedOneExample" configuration
- Now go back to the FeedOne component and resubmit the http://www.searchtechnologies.com URL to the pipeline (see above).
- Look at the console window where you first ran "startup.bat". You should see "Hello World!" followed by a JSON representation of the Aspire document.
- For more information on the Groovy scripting language, go here: http://groovy.codehaus.org/
- For more information on methods available on the "doc" variable in your Groovy script go to:
- AspireObject
- The AspireObject javadoc page