Commands

Install Service

This command to install Aspire as a Windows service and must be executed as Administrator (see instructions below for how to do this):

> bin\installServiceaspire.bat -install_service [ServiceName]

ServiceName - [Optional] Specify the name of the Windows Service as stored in the Windows registry. Defaults to "AspireService" if not specified. If you want to have multiple Aspire services running simultaneously, you will need to give them different service names.

The Aspire installation in which the command is run will be the installation which is installed. Therefore, be sure to set your current directory properly before executing the command.

The following commands provide usage instructions for the installServiceaspire.bat script:

> bin\installServiceaspire.bat -help
> bin\installServiceaspire.bat/?
> bin\installServiceaspire.bat --help 

Important:

Please notice that if you use this command to install Aspire as a service, then JVM parameters have to be added to installService.bat. See line 181 of the script:

178 rem Set the felix properties
179
180
181 set JAVA_PROPS_PRUNSRV=-Xrs#-Dfelix.config.properties=file:config/felix.properties#-Dcom.searchtechnologies.aspire.home=%ASPIRE_HOME%

Check that different VM options are separated by a # sign, instead of a single space.

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Apache Software Foundation\Procrun 2.0\{Aspire_Service_Name}\Parameters\Java

Image Modified Image Modified Image Modified Image Modified Image Modified

If your Options field has your added Java options, then you are fine.

Please notice that if you have already installed Aspire as a service before adding these options, you will have to remove the existing service and create a new one after updating the file installService.bat to notice any changes.

Remove Service

This command removes the specified Windows Service from the registry and must be executed as Administrator (see instructions below for how to do this):):

 > bin\removeServiceaspire.bat -remove_service [ServiceName]

ServiceName - [Optional] The name of the Windows Service to be removed. Defaults to "AspireService" if not specified. Should be the same as the name specified when you executed "installServiceaspire.bat -install_service".

The following commands provide usage instructions for the removeServiceaspire.bat script:

> bin\removeServiceaspire.bat -help
> bin\removeServiceaspire.bat --help
> bin\removeServiceaspire.bat/??

Instructions

Prerequisites

Make sure you have everything installed as instructed at Prerequisites to Connectors and Content Processing (Java, Maven, MongoDB)

Instructions

Prerequisites

Your JAVA_HOME environment variable must be set to a valid Java JRE available on your machine.

The version of Java you should use depends on the Aspire version you are targeting to:

on your machine.

STEP 1: Run a Windows Command Shell as Administrator

You can only install or remove Windows Services as an administrator. To do this:

• Find the Windows Command Prompt in your Start Menu.
  • This is typically in Start / All Programs / Accessories
• Right-click on the Windows Command Prompt.
• Select "Run As Administrator" in the pop-up menu.

STEP 2: Set your working directory to your Aspire distribution

The scripts must be run from the Aspire home directory of the distribution you want to run as a Windows service. It will install the service specifically for the Aspire distribution of this directory. 

STEP 3: Run bin\

aspire.bat -install_service

To install the service, simply run the "installServiceaspire.bat -install_service" script in the bin directory. For example:

> bin\installServiceaspire.bat  -install_service
Current System Architecture: AMD64
Windows Service Name:  AspireService
Aspire Home:  c:\Users\pnelson\Desktop\cws\apps-demo2\target\apps-demo2-1.0-SNAPSHOT-distribution.dir

Java VM:  C:\Program Files\Java\jdk1.68.0_3173\jre\bin\server\jvm.dll
Creating Service...


Service AspireService created.

This script takes the name of the service to install as a single, optional argument. This defaults to "AspireService". If you need to install multiple Windows services for multiple Aspire installations, be sure to install them with different names.

If Something Goes Wrong

• Check the ${aspire.home}\log\procrun.log file for detailed error messages.
• Check the %SystemRoot%the %SystemRoot%\System32\LogFiles\Apache\procrun.*.log file for detailed error messages.
• See further troubleshooting notes below.
  
  

STEP 6: Set the Local Repository for Maven

You will need to specify the location of the local repository for your Aspire distribution if:

1. You are running the Windows Service with a different "Log On" user, AND
2. Aspire is configured to download components and applications automatically from Maven (this is the default)

Aspire uses standard Maven APIs to download those artifacts. When the artifacts (i.e., the JAR files) are downloaded they are stored in a "local repository" (a specific directory on disk) and accessed from there. The advantage of a local repository is that all instances of Aspire on the same machine can share the same JAR files, saving a lot of space on the computer.

The safest way to set your local repository is to edit the "${aspire.home}/config/settings.xml" file. In that file you should see the following <repository> tag. Specify the <localRepository> as shown below:

<repositories> <settings>
  .
  
	<defaultVersion>3.2</defaultVersion>
  .
  
	<repository type="maven">
    		<defaultVersion>2.2.2</defaultVersion>
    		<localRepository>bundles/aspire</localRepository>
    <remoteRepositories>
      <remoteRepository>
         <id>stPublic</id>
         <url>http		<remoteRepositories>
			<remoteRepository>
				<id>stPublic</id>
				<url>https://repository.searchtechnologies.com/artifactory/simple/community-public/</url>
        <user>USERNAME</user>
        <password>PASSWORD</password>
      </remoteRepository>
    				<user>YOUR-REGISTERED-USERNAME</user>
				<password>YOUR-REGISTERED-PASSWORD</password>
			</remoteRepository>
		</remoteRepositories>
    </repository>
</settings>repositories>

The above settings will create a local maven repository just for the one Aspire distribution. It's possible to share the local repository for all Aspire distributions and all users of the same machine. Just specify the appropriate (shared) directory under <localRepository> and make sure that all users have the necessary access to it.

STEP 7: Launch Aspire

You should now be able to select your new Aspire Service and click on "Start" to start it.

If something goes wrong, check the following:

• The Windows Event Viewer

  This can be found in Control Panel / Administrative Tools (in the System and Security category) / Event Viewer Errors launching the service will be written here.

• ${aspire.home}/log/procrun.log

  Errors launching the service from Apache procrun

• ${aspire.home}/log/AspireService-stderr.log

  Aspire standard error output

• ${aspire.home}/log/AspireService-stdout.log

  Aspire standard error output

• ${aspire.home}/log/aspire.log

  The official, top-level Aspire log.

Install Multiple Windows Services (optional)

You can install multiple Aspire Windows services at a time. This will typically happen when:

1. You have multiple Aspire distributions installed on your Windows computer
2. They use different port addresses
   • See Changing the Aspire Port Address
   (Aspire 2)
   • to specify the port address for your Aspire system

Sometimes, you'll need multiple installations so they can run as different Windows users for security purposes. Or maybe you want multiple installations for testing and debugging.

To install multiple Windows Services for multiple installations, just execute the "installService.bat" program for each distribution, using a different service name for each one.

Note that the default name (if none is specified) is "AspireService".

Notes / Troubleshooting

Unable to Install: Marked for Deletion

When this occurs, you'll see the following in the procrun log:

[2016[2012-04-02 23:46:43] [info]  Commons Daemon procrun (1.0.10.0 64-bit) started
[20122016-04-02 23:46:43] [info]  Service AspireService name AspireService
[20122016-04-02 23:46:43] [error] The specified service has been marked for deletion.
[20122016-04-02 23:46:43] [error] Failed installing 'AspireService' service
[20122016-04-02 23:46:43] [error] The specified service has been marked for deletion.
[20122016-04-02 23:46:43] [error] Commons Daemon procrun failed with exit value: 8 (Failed to install service)
[20122016-04-02 23:46:43] [error] The specified service has been marked for deletion.

Cause 1: Close the Services Control

If you have the Services interface displayed when you delete a Windows Service (for example, using the "removeService.bat" script provided with Aspire), then the service will only be marked for deletion.

In other words, it will not be actually removed until you close down the "Services" user interface. This is because the Services control locks the services database from these sorts of edits.

If you fail to do this, you will see the following in your "${aspire.home}/log/procrun.log" file:

Cause 2: Services are still Running

If you have a previous version of the Aspire Service which is still running (according to the Services user interface control), then it will not be deleted until the service is stopped.

Open up the Services control, select the Aspire service, and then use the "Action / Stop" command to stop the service.

The service should automatically be removed (if it is marked for deletion), and then you should be able to install a new one.

Note: It's possible that the service is still "Running" even if the Aspire services have been shut down. This will happen if the servers are shutdown using the Aspire admin interface, or if they are killed using the Task Manager. 

Applications are Not Launched - Applications Missing from Pull-Down

This occurs when there's a problem accessing Maven. You should also see the following in "AspireService-stderr.log":

 com.searchtechnologies.aspire.services.AspireException: The local Maven repository specified in the
   Aspire settings.xml file (C:\Users\aspire_crawl_account/.m2/repository) does not exist or is not a
   directory. Note that if the <localRepository> tag is not specified, then it will default to ".m2/repository"
   inside the user's home directory. (component='aspire', componentFactory='aspire-application')
       at com.searchtechnologies.aspire.application.MavenRepository.initialize(MavenRepository.java:81)
       at com.searchtechnologies.aspire.application.RepositoryManager.initialize(RepositoryManager.java:96)
       at com.searchtechnologies.aspire.application.AspireApplicationImpl.autoStart(AspireApplicationImpl.java:183)
       at com.searchtechnologies.aspire.application.AspireActivator.run(AspireActivator.java:136)
       at java.lang.Thread.run(Thread.java:662)

To fix this problem, see Step 6 above, setting the Maven Local Repository.

Windows Service Error - Java Executable doesn't exist

Aspire Windows Service Error - The specified Java Executable (C:\WINDOWS\system32\java.exe) either doesn't exist or is not a file.

  Service cannot be started. System.Exception: Aspire Service - Process Did Not Start.
    at AspireWindowsService.AspireWindowsService.OnStart(String[] args)
    at System.ServiceProcess.ServiceBase.ServiceQueuedMainCallback(Object state)

This probably means that your $JAVA_HOME environment variable is not set properly.

Shared Port Addresses

Other problems could be caused if something is already using port 50505 (the default Aspire port). In order to determine which port addresses are in use on a Windows machine, use the command:

 netstat -ano 

Suppose all of your Aspire servers use ports starting with “505”. Suppose you suspect that Aspire is not working because someone else already has Aspire running on the machine. Use the following to see what 505 ports are in use on the machine:

netstat -ano | grep 505 

Windows Service

Not Starting

If starting Aspire Service fails, check the Windows System log as well. It may contain this message:

The AspireService service terminated with the following service-specific error: The operation completed successfully.

Check %SystemRoot%\System32\LogFiles\Apache\procrun.*.log:

[20152016-06-25 10:35:48] [info]  Commons Daemon procrun (1.0.10.0 64-bit) started
[20152016-06-25 10:35:48] [info]  Running 'AspireService' Service...
[20152016-06-25 10:35:48] [info]  Starting service...
[20152016-06-25 10:35:48] [error] Missing service ImageFile
[20152016-06-25 10:35:48] [error] ServiceStart returned 1
[20152016-06-25 10:35:48] [info]  Run service finished.
[20152016-06-25 10:35:48] [info]  Commons Daemon procrun finished

Check the service configuration in the Windows registry and make sure it has been installed properly.

How

It Works

The Windows service is launched using the prunsrv service from Apache Commons Daemon

When the service is "Start"ed, prunsrv launches “java.exe” as a process, with all of the appropriate arguments.

• It redirects the standard error of this process to a log/AspireService-stderr.log.
• It redirects the standard output of this process to a log/AspireService-stdout.log.

When the service is "Stop"ed, the 'shutdown.exe' program is called. This program will send a Shutdown command to the service as an HTTP request (using the http://localhost:50505/aspire?cmd=shutdown URL).