Installing as a Windows service

This guide will help you set up the Aluma File System Agent as a Windows service. The guide assumes a basic familiarity with the File System Agent (run as an application), installing and configuring Windows services, creating Windows user accounts and giving users permissions to folders.

In the following steps we assume you will install the agent to a folder called C:\aluma-fsa. You can choose another folder - just replace the folder in all the commands used below.

Here's what you'll need before you start:

The aluma-file-system-agent.exe file. You can download this from here: https://downloads.aluma.io/file-system-agent/windows/aluma-file-system-agent.exe .
A dedicated Windows user that has read/write permissions to C:\aluma-fsa (or another folder containing the configuration files, database and log files) and to the folders used by File System Agent triggers and exporters.

Preparing for installation

Before installing the service you should authenticate and configure File System Agent using it as an application so you can use the user interface. Run File System Agent and ensure that:

it is authenticated to the Aluma service
you have enabled triggers and exporters for the projects you intend to use.

Take a note of the folders that your triggers and exporters are using. Ensure that the user that the services runs as has both read & write permissions for all of these folders.

Installing and starting the service

Now follow these steps to install and start the service:

Create a folder for the service: Create a folder that will contain the executable file and the service configuration. In the following steps we assume this folder is C:\aluma-fsa.
Copy the agent executable: Copy aluma-file-system-agent.exe to C:\aluma-fsa.
Copy the agent configuration folder: Copy the files in folder C:\\Users\<your username>\.aluma\\file-system-agent to C:\\aluma-fsa. You do not need to copy agent.log and window.yaml.
Open a command prompt with Administrator permissions: Open a command prompt window. In most Windows setups, you can search for "command prompt" in the Start menu and click the "Run as administrator" option. Navigate to C:\\aluma-fsa by typing cd C:\\aluma-fsa.
Install the service: Type the following command and press Enter:
aluma-file-system-agent service install --config-dir c:\\aluma-fsa
You will see Installing service... then Installing service... [OK] when the installation is complete.
Change the user: When installed, the service is configured to run as LocalService. Open the Services app (you can search for "services" in the start menu) and find the "Aluma File System Agent" service. Open the service properties and change the "Log on as" settings to the dedicated user you have created for the service.
Configure the service to restart on error: On the "Recovery" tab in the service properties, change the "First failure", "Second failure" and "Subsequent failures" to "Restart the service".
Start the service: Start the service by clicking the "Start" button on the service properties or in the services app toolbar, or by typing this command and pressing Enter:
aluma-file-system-agent service start
Check the service is running correctly: Open C:\\aluma-fsa\\agent.log, scroll to the end and check that log messages are being written to the file. Put a file in your trigger folder and check it is processed and export files are written correctly. Check the log file for errors if necessary. Folder permissions are the most likely source of errors.

Stopping the service

You can stop the service using the Windows services app or by opening a "Run as administrator" command prompt and typing aluma-file-system-agent service stop

Uninstalling the service

You can uninstall the service by opening a "Run as administrator" command prompt and typing aluma-file-system-agent service uninstall

Editing trigger or exporter folders

By following the steps above, the service will have a separate configuration to the one used when you run the agent as an application, where the configuration is in C:\\Users\<your username>\.aluma\\file-system-agent.

If you need to change trigger or exporter folders you should:

Stop the service
Make the changes
Start the service again

You can change trigger or exporter folders using any of these methods:

Edit the triggers.yaml and exporters.yaml files in C:\\aluma-fsa directly, or
Run the application pointing to the service's configuration folder by opening a command prompt and running the command C:\\aluma-fsa\\file-system-agent --config-dir C:\\aluma-fsa, or
Run the application pointing to the service's configuration folder by creating a shortcut with the command C:\\aluma-fsa\\file-system-agent --config-dir C:\\aluma-fsa.

Installing multiple instances of the service

If you have multiple Aluma accounts it is possible to install multiple instances of the File System Agent service on the same machine, with each instance configured to use a different account.

Before installing the services, authenticate and configure multiple instances of the agent running as an application. Start the application with an additional command-line parameter that specifies the folder that will contain the configuration files, database and log files: aluma-file-system-agent service install --config-dir c:\\aluma-fsa\\account1. Authenticate and configure your triggers and exporters, then repeat with the other account.

When you are ready to install the services, follow the instructions above for each account but adjust the installation command to specify a different configuration directory for each instance and specify a custom name for each service instance using the --name parameter:

aluma-file-system-agent service install --config-dir c:\\aluma-fsa\account1 --name 'File System Agent account 1'