ErgoTechWiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Running a TransSECS deployment as a Windows service ======

A TransSECS deployment is the folder TransSECS builds for a project. It holds ''<ProjectName>Runtime.jar'', ''log4j2.xml'', ''ErgoTechConfiguration.properties'' and ''run.bat''. Started with ''run.bat'', it runs in a console window and stops when someone closes that window or logs off. To have it start with Windows and restart after a failure, run it as a Windows service.

This page uses **WinSW 2.12.0**, a small open-source program that runs any command as a Windows service. You put one ''.exe'' and one ''.xml'' file in the deployment folder, edit the ''.xml'' for your project, and install it.

Read [[starting_mix_transsecs_deployments_on_windows|Running TransSECS deployments]] on the bottom half of this page first. Everything there about Java, licences, the working directory and logging applies to a deployment run as a service too.

This page is the detail behind [[start_transsecs_deployments_automatically|Starting TransSECS deployments automatically on Windows]], which compares a service with the simpler Startup folder.

===== 1. What you need =====

  * **A deployment that already works from ''run.bat''.** Start it by hand once, on this machine, and check the log for ''Valid IOT System Runtime License detected''. A service hides the console, so sort out licence and configuration problems before you install it.
  * **WinSW 2.12.0, the ''WinSW-x64.exe'' file.** It is a 64-bit build that needs no .NET installation. If your TransSECS installation did not include it, download it from the WinSW releases page: [[https://github.com/winsw/winsw/releases/tag/v2.12.0|WinSW v2.12.0]]. (''WinSW-x86.exe'' is the 32-bit build; ''WinSW.NET461.exe'' also works but needs .NET Framework 4.6.1 or later.)
  * **A Java 11 runtime inside the deployment folder** (section 2).
  * **Administrator rights** to install and remove the service.
  * **A local disk.** Put the deployment on a local drive such as ''C:\''. The service runs as the LocalSystem account, which cannot see mapped network drives like ''Z:''.

===== 2. Copy a Java runtime into the deployment =====

The service does not run with your PATH, and the Java that TransSECS uses is not on any PATH. Give the deployment its own Java:

  - Copy the ''jre'' folder from the TransSECS installation, ''<TransSECS installation>\MIStudioSuite\jre'', into the deployment folder, so that you have ''<deployment>\jre\bin\java.exe''.
  - Check it: open a Command Prompt in the deployment folder and run ''jre\bin\java -version''. It must report version 11.

Copy the folder rather than pointing the service at the one in the TransSECS installation. Upgrading or uninstalling TransSECS replaces that folder and would break the service. With its own copy, the deployment can also be moved to a machine that has no TransSECS installed. ''run.bat'' looks in ''.\jre'' as well, so the hand-started deployment can use the same Java.

The ''jre'' in a Windows TransSECS installation is a Windows runtime. It will not run on Linux.

===== 3. Add the wrapper files =====

  - Copy ''WinSW-x64.exe'' into the deployment folder and rename it after the deployment, for example ''GEMHostService.exe''.
  - In the same folder, create a text file with **the same base name** and the extension ''.xml'', for example ''GEMHostService.xml''. WinSW finds its configuration by that name.
  - Paste in the example below and change the parts in the table that follows.

Example for a project called ''GEMHost'':

<code xml>
<service>
  <id>GEMHostDeployment</id>
  <name>TransSECS GEMHost</name>
  <description>TransSECS deployment for the GEMHost project.</description>

  <executable>%BASE%\jre\bin\java.exe</executable>
  <arguments>-Dnashorn.args="--no-deprecation-warning" -cp ".;.\*" deploy.GEMHost.EquipmentController</arguments>
  <workingdirectory>%BASE%</workingdirectory>

  <startmode>Automatic</startmode>
  <delayedAutoStart/>

  <onfailure action="restart" delay="10 sec"/>
  <onfailure action="restart" delay="30 sec"/>
  <resetfailure>1 hour</resetfailure>
  <stoptimeout>15 sec</stoptimeout>

  <log mode="roll-by-size">
    <sizeThreshold>10240</sizeThreshold>
    <keepFiles>8</keepFiles>
  </log>
</service>
</code>

''%BASE%'' is filled in by WinSW with the folder that holds the renamed ''.exe'', which is the deployment folder.

^ Element ^ What it does ^ What to change ^
| ''id'' | The internal service name. Letters and digits only, unique on the machine. | One per deployment, e.g. ''GEMHostDeployment''. |
| ''name'' | The name shown in the Services window. | Something an operator will recognise. |
| ''description'' | The description shown in the Services window. | Optional. |
| ''executable'' | The Java to run. | Leave it, once the ''jre'' folder is copied in (section 2). |
| ''arguments'' | The Java command line. | Replace ''GEMHost'' in ''deploy.GEMHost.EquipmentController'' with your project name. Copy the class name from the last ''java'' line of the deployment's ''run.bat'' to be sure. Add any extra Java options before ''-cp'', for example ''-Xmx512m''. |
| ''workingdirectory'' | The folder the deployment runs in. | Leave it as ''%BASE%''. The deployment reads its settings and licence from its working directory. |
| ''startmode'' and ''delayedAutoStart'' | Start with Windows, a little after the other automatic services so the network is up. | Use ''Manual'' and remove ''delayedAutoStart'' if it should only start when someone starts it. |
| ''onfailure'' and ''resetfailure'' | If the deployment stops on its own, restart it after 10 seconds, then after 30 seconds for later failures. The failure count resets after an hour without one. | Use ''<onfailure action="none"/>'' to leave it stopped instead. |
| ''stoptimeout'' | How long Windows waits for the deployment to shut down before ending it. | Usually leave it. |
| ''log'' | Keeps the console output (see section 5) in files of up to 10 MB, 8 old files kept. | The size is in KB. |

The class path ''.;.\*'' takes every jar in the deployment folder. That covers ''<ProjectName>Runtime.jar'' and anything else ''run.bat'' lists, such as ''AzureSDKRuntime.jar'' in an Azure deployment.

===== 4. Install and start the service =====

Open a Command Prompt **as Administrator**, change to the deployment folder, and run:

<code>
GEMHostService.exe install
GEMHostService.exe start
GEMHostService.exe status
</code>

''status'' should say ''Started''. The service now also appears in the Services window (''services.msc'') under the ''name'' you gave it, where it can be started and stopped like any other.

If Windows blocks the ''.exe'' because it was downloaded, open its Properties, tick **Unblock**, and try again.

===== 5. Check that it is running =====

  * **''GEMHostService.out.log'' and ''GEMHostService.err.log''**, in the deployment folder, hold what ''run.bat'' would have shown in its console window.
  * **The deployment's own log files** are written exactly as when it is started with ''run.bat'', as ''log4j2.xml'' says.
  * Look for ''Valid IOT System Runtime License detected'' and the first ''SENT:'' / ''RECEIVED:'' pair, as for a hand-started deployment.

===== 6. Stopping, changing and removing the service =====

^ To ^ Run (as Administrator, in the deployment folder) ^
| Stop it | ''GEMHostService.exe stop'' |
| Restart it | ''GEMHostService.exe restart'' |
| Remove it | ''GEMHostService.exe stop'', then ''GEMHostService.exe uninstall'' |

  * **Stopping** asks the deployment to shut down as Ctrl+C in its console window would. If it has not stopped after ''stoptimeout'', Windows ends it. The equipment on the other side sees the connection close; that is normal.
  * **Changes to ''arguments'', ''executable'' or ''log''** take effect the next time the service starts. Restart it.
  * **Changes to ''id'', ''name'', ''description'' or ''startmode''** are stored in Windows when the service is installed. Stop and uninstall the service, then install it again.
  * **Rebuilding the deployment** in TransSECS replaces the jar but does not touch the ''jre'' folder or the two WinSW files. Stop the service before you rebuild, and start it afterwards.

===== 7. More than one deployment on a machine =====

Give each deployment its own folder, its own copy of the renamed ''.exe'' and ''.xml'', and its own ''id'' and ''name''. Two deployments on one machine must not use the same HSMS port.

===== 8. When it does not start =====

^ What you see ^ Cause ^
| The service starts and stops again at once | Read ''GEMHostService.err.log'' and ''GEMHostService.out.log'' first. |
| It stops at once and **both logs are empty** | A trial-built deployment past its expiration date exits without a message. See the licences section of [[starting_mix_transsecs_deployments_on_windows|Running TransSECS deployments]]. Rebuild with a current installation. |
| ''Could not find or load main class deploy....EquipmentController'' | The project name in ''arguments'' is wrong. Compare it with the ''java'' line of ''run.bat''. |
| The service will not start and the ''.out.log'' is not created | ''executable'' does not point at a Java: check that ''jre\bin\java.exe'' exists in the deployment folder. |
| A message naming the **prelicense code** instead of the licence line | The runtime licence file is missing from the deployment folder, or is for another machine. Compare with what ''run.bat'' reports. Never rename a licence file. |
| The deployment's settings seem to be ignored | ''workingdirectory'' is not the deployment folder. |
| It works from ''run.bat'' but not as a service when the deployment is on a network drive | Move it to a local disk. |