Run Aspire as a Windows Service, which allows you to launch and shutdown Aspire using the standard Windows Services administration tool (typically located in Control Panel > Administrative Tools > Services).

Notes

  • Apache Procrun is used to wrap Aspire as the Windows Service. It is included in the standard Aspire distribution.  Use the provided "aspire.bat" script to install or remove Aspire as a Windows Service.
  • The Windows Services administration tool must be started with the "Run as administrator" option. Otherwise, it will not be possible to start, stop, and restart options.

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\aspire.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 aspire.bat script:

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

You can check that your Java properties (memory options, etc) are correct by going to the Windows registry.

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


Registry1.png Registry2.png Registry3.png Registry4.png Registry5.png

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\aspire.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 "aspire.bat -install_service".

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

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

Instructions


Prerequisites

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

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

STEP 1: Run a Windows Command Shell as Administrator

Running a Windows Command Prompt 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

This is also known as ${aspire.home}

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 "aspire.bat -install_service" script in the bin directory. For example:

> bin\aspire.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.8.0_73\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%\System32\LogFiles\Apache\procrun.*.log file for detailed error messages.
  • See further troubleshooting notes below.

STEP 4: Set Other Windows Service Properties

The install service is installed with "Manual" for startup and with "Local System Account" as the log-on user. You will likely want to change these.

  1. Open up Control Panel / Administrative Tools (in the System and Security Category) / Services
  2. Find the service which you installed, and edit its properties

    Should be "AspireService" if you specified the default name

  3. Change the Startup to "Automatic" so the service will be started automatically when the computer is rebooted
  4. Select the "Log On" tab, and then specify the username and password that should be used to run the service.

Windows Service Properties

STEP 5: Provide Access Rights to your Log On Account

If you choose to have your Windows Service log on as a specific user, be sure to give that user access to your Aspire distribution.

Go to the folder in your Windows Explorer, right-click, and choose "properties", then the "Security" tab. Add the user which will be running Aspire to the list of users for that folder and give it "Full Control" rights.

Rights should automatically be inherited by all nested folders and files within the distribution.


Set User Security Rights

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>
    
	<defaultVersion>4.0</defaultVersion>
    
	<repository type="maven">
		<defaultVersion>2.2.2</defaultVersion>
		<localRepository>bundles/aspire</localRepository>
		<remoteRepositories>
			<remoteRepository>
				<id>stPublic</id>
				<url>https://repository.searchtechnologies.com/artifactory/public/</url>
				<user>YOUR-REGISTERED-USERNAME</user>
				<password>YOUR-REGISTERED-PASSWORD</password>
			</remoteRepository>
		</remoteRepositories>
    </repository>
</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

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

This assumes you have Cygwin installed


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:

[2016-06-25 10:35:48] [info]  Commons Daemon procrun (1.0.10.0 64-bit) started
[2016-06-25 10:35:48] [info]  Running 'AspireService' Service...
[2016-06-25 10:35:48] [info]  Starting service...
[2016-06-25 10:35:48] [error] Missing service ImageFile
[2016-06-25 10:35:48] [error] ServiceStart returned 1
[2016-06-25 10:35:48] [info]  Run service finished.
[2016-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).