=====Setting up MIX as a Service on Windows=====

This article provides instructions on how to set up MIX as a service on Windows. As a service you can use the Windows Service manager panel to stop and start MIX, and to set it to run automatically when Windows starts. The wrapper software is distributed with a permissive MIT license.

These instructions use the service wrapper (WinSW) from https://github.com/winsw. This is an active open-source project and is very easy to set up and use. There are more features available for this wrapper than the basic setup described in this article, but the basic setup should be useful for most MIX installations.

Read more about the wrapper at the bottom part of the page at https://github.com/winsw/winsw.

====Differences in running MIX as a Service vs as an executable (MIX.exe)====

When you run MIX.exe (the MIX executable) you are actually running a Windows wrapper on top of a simple Java application. This WinSW application is also a wrapper. So you cannot run a wrapper with a wrapper (too many configuration conflicts). So instead of running MIX.exe the WinSW service wrapper will run a simple batch file to start MIX, with the same basic Java startup configurations set as the MIX.conf file sets for running the MIX.exe wrapper. Do not be concerned at this point in the instructions, setting up the batch file to run mix is easy and this is just a note so you understand what is ahead.

====Get the Service Wrapper Files====

The first step to setting up the wrapper for MIX is to download the main executable and a configuration from https://github.com/winsw/winsw/releases .

WinSW can be set up on x86 (32-bit) or x64 (64-bit) and the executable you select to download will depend on the MIX deployment Windows version and architecture. The most straightforward setup is for Windows 10+ which has .net 4.61+ installed (it will be by default on Windows 10+ systems). Download the current release (not the beta release). As of the date of this article the current release is 2.11, and version 3 is in alpha phase and probably should not be used except for experimentation. The links below are for version 2.11 and you should check if there is a later version.

The executable to download for Windows 10 (and systems using .net 4.61 or newer) is https://github.com/winsw/winsw/releases/download/v2.11.0/WinSW.NET461.exe . If you are running an X86 version of Windows or an older version, please read the documentation page (link in the first section above) to understand which exe you will need.

Also download the simple configuration example (sample-minimal.xml) from https://github.com/winsw/winsw/releases/download/v2.11.0/sample-minimal.xml . You can also download the more extensive (examples of every configurable property) configuration (sample-allOptions.xml) from https://github.com/winsw/winsw/releases/download/v2.11.0/sample-allOptions.xml .

==== Copy the Wrapper for MIX====

Make sure you have set up the MIX runtime distribution using the instructions on this wiki page [[runtimesetup#making_a_mix_runtime_installation|Making a Runtime Installation]]. 
Copy the executable for the service wrapper and the simple (minimal) configuration file into the MIX runtime (mixruntime) directory.

====Rename the Wrapper====

Rename the executable (i.e. WinSW.NET461.exe) to the name of the service. For MIX, rename WinSW.NET461.exe to mixruntime.exe. Rename the minimal configuration xml to match this name; change "sample-minimal.xml" to mixruntime.xml.

====Configure the Service Wrapper====

Edit mixruntime.xml in NotePad+ or another text only editor (such as EditPad if you do not have NotePad++). 

You will see these defaults:

<code xml>
<!--
  MIT License

  Copyright (c) 2008-2020 Kohsuke Kawaguchi, Sun Microsystems, Inc., CloudBees,
  Inc., Oleg Nenashev and other contributors

  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to deal
  in the Software without restriction, including without limitation the rights
  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  copies of the Software, and to permit persons to whom the Software is
  furnished to do so, subject to the following conditions:

  The above copyright notice and this permission notice shall be included in all
  copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  SOFTWARE.
-->

<!--
 This is an example of a minimal Windows Service Wrapper configuration, which includes only mandatory options.
 
 This configuration file should be placed near the WinSW executable, the name should be the same.
 E.g. for myapp.exe the configuration file name should be myapp.xml
 
 You can find more information about the configuration options here: https://github.com/kohsuke/winsw/blob/master/doc/xmlConfigFile.md
 Full example: https://github.com/kohsuke/winsw/blob/master/examples/sample-allOptions.xml
-->
<service>
  
  <!-- ID of the service. It should be unique across the Windows system-->
  <id>myapp</id>
  <!-- Display name of the service -->
  <name>MyApp Service (powered by WinSW)</name>
  <!-- Service description -->
  <description>This service is a service created from a minimal configuration</description>
  
  <!-- Path to the executable, which should be started -->
  <executable>%BASE%\myExecutable.exe</executable>

</service>
</code>

Change the values (id,name, and executable) at the bottom so that they are changed to the parameters you want to use for the service:

<code xml>
<!--
  MIT License

  Copyright (c) 2008-2020 Kohsuke Kawaguchi, Sun Microsystems, Inc., CloudBees,
  Inc., Oleg Nenashev and other contributors

  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to deal
  in the Software without restriction, including without limitation the rights
  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  copies of the Software, and to permit persons to whom the Software is
  furnished to do so, subject to the following conditions:

  The above copyright notice and this permission notice shall be included in all
  copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  SOFTWARE.
-->

<!--
 This is an example of a minimal Windows Service Wrapper configuration, which includes only mandatory options.
 
 This configuration file should be placed near the WinSW executable, the name should be the same.
 E.g. for myapp.exe the configuration file name should be myapp.xml
 
 You can find more information about the configuration options here: https://github.com/kohsuke/winsw/blob/master/doc/xmlConfigFile.md
 Full example: https://github.com/kohsuke/winsw/blob/master/examples/sample-allOptions.xml
-->
<service>
  
  <!-- ID of the service. It should be unique across the Windows system-->
  <id>MIXRuntime</id>
  <!-- Display name of the service -->
  <name>MIX Runtime Service (powered by WinSW)</name>
  <!-- Service description -->
  <description>Run MIX as a Windows Service</description>
  
  <!-- Path to the executable, which should be started -->
  <executable>%BASE%\run_mix.bat</executable>

</service>

</code>

====Final Setup: Copy and edit the batch file to start MIX====

In the MIX directory is a subdirectory called "scripts". Go to this subdirectory and copy the run_mix.bat, then paste this to the main MIX directory. One line needs to be changed so that the logging is as expected (file logging). Open run_mix.bat in Notepad++ or your text editor, you will see:

<code batch>
set path=..\jre\bin;.\lib\;%path%
java -version
set classpath=./*;./lib/*;./lib/jdbc/*;
rem ./lib/OPCUAServer.jar;./lib/TransSECSRuntime.jar;./lib/opcua/*;./lib/jdbc/*;

rem java -Djava.io.tmpdir=C:\plcshare -Dvib.sharedplcsimulation=true -DOmronFins.simulate=true -Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,address=8000,suspend=n -Dlog4j.configuration=log4j.console.xml  -DLoggerClass=Log4JLogger com.ergotech.mix.server.HeadlessController

java -Dlog4j.configuration=log4j.console.xml -Xrunjdwp:transport=dt_socket,server=y,address=8000,suspend=n -DLoggerClass=Log4JLogger com.ergotech.mix.server.HeadlessController

</code>

change the line that says:

<code>java -Dlog4j.configuration=log4j.console.xml -Xrunjdwp:transport=dt_socket,server=y,address=8000,suspend=n -DLoggerClass=Log4JLogger com.ergotech.mix.server.HeadlessController</code>

to

<code>
java -Dlog4j.configuration=log4j.xml -Xrunjdwp:transport=dt_socket,server=y,address=8000,suspend=n -DLoggerClass=Log4JLogger com.ergotech.mix.server.HeadlessController </code>

so that the log4j.xml file is changed from log4j.console.xml to log4j.xml.

====Install the Service====

Open a command shell in the mixruntime directory where you have been editing the files. 

type this into the console window:

<code> mixruntime install </code>

you should see some feedback in the console, similar to:

C:\Users\Public\mixruntime>mixruntime install
2022-03-24 15:44:21,848 INFO  - Installing service 'MIX Runtime Service (powered by WinSW) (MIXRuntime)'...
2022-03-24 15:44:21,864 INFO  - Service 'MIX Runtime Service (powered by WinSW) (MIXRuntime)' was installed successfully.

====Monitoring the Service====

To see what you have accomplished, run the Windows Service panel. You can find this in the Windows start menu under Windows Administrative Tools, then scroll down to Services (it is actually running this: C:\WINDOWS\system32\services.msc).

When you run the Services panel you can find the "MIXRuntime" service that you just installed:

{{:pasted:20220324-165530.png}}

You can see that the service is set up to run automatically when Windows starts (more precisely, when the LocalSystem account starts).

if you ever need to uninstall the service, use mixruntime uninstall.

====Starting the Service====

You can start MIX by right clicking in the Status column of the Services panel for the MIXRuntime service and selecting Start. After you do this you will see that the service is running, so MIX is running.

{{:pasted:20220324-165849.png}}

You can also start the service in the command shell (or write a batch file to do this) by typing "mixruntime start".

====Stopping the Service====

The service can be stopped by right clicking on the "Running" status in the Service console and selecting "Stop". Alternatively you can stop the service on the command line using "mixruntime stop".