Installing Frends Agent

In this guide you will learn how to configure an isolated Frends Environment and install an on-premise Frends Agent to start executing your integrations on-premise with only logging and configuration done in the cloud.

Requirements

You will need the following prerequisites to follow this guide.

Admin permissions to a Frends Tenant

You will need to have the Administrator role for the Frends Tenant the Agent will be installed to.

You should also have an Environment and an Agent Group prepared in Frends. You can follow the guide about Creating new Environments & Agent Groups for this.

Server requirements

You will need a server you have administrator access to, in order to install the Frends Agent.

In addition, the server should fulfill the following requirements.

Operating system

Microsoft Windows 10, 11, or Windows Server 2019 or later.

Ubuntu Server 22.04 LTS or newer.

Local or Active Directory user account that is in local admin group on the server.

Alternatively, an operational Kubernetes or Docker environment for containerized deployment.

Software

Latest Agent versions require .NET 8.0 runtime to be installed on the server.

Legacy Agents running on Microsoft Windows platform require .NET Framework 4.7.2 runtime.

Hardware minimum requirements

The host machine can have at minimum 2 vCPU, 4 GB of RAM, and 32 GB of disk space if the Agent is not under a heavy load. This could be the case if the Agent is used in the Development Environment.

Hardware recommendations

The host machine should ideally have 4 vCPU, 8 GB of RAM, and 100 GB of disk space.

Memory, disk space and vCPU depends largely on the usage of your Agent. More memory may be required if there are hundreds of Processes or, for example, if you have Processes doing XSL transformations on large XML files. More disk space may be required if you plan on storing a large number of files.

It is usually better to have two Frends Agents with less capable hardware than one with powerful hardware.

Connectivity requirements

Hosting a Frends Agent on your server requires the following details to be set up and confirmed.

Outbound connectivity

Frends 5.7 and later require outbound access to the following:

• Frends UI: <tenant>.frendsapp.com on port 443

• Azure Service Bus: Ports 443, 5671 and 5672 are needed to be open towards Azure Service Bus

• Azure Blob Storage: Port 443 is needed for Azure Blob Storage

You can check the Microsoft's documentation about Azure Service Bus and Azure Blob Storage. As the IP addresses of the Azure services may change, these may have to be opened without IP restrictions.

Azure Service Bus is used to allow the Agent to communicate with the Frends Core, that is located in Azure cloud. This in turn enables the connectivity between the Frends UI and the Agents.

Azure Blob Storage is needed to store larger logging data and messages that do not fit in a single Azure Service Bus message (over 200 kb), as well as to retrieve compiled Processes during Process or Agent deployment.

Alternatively, if outbound connectivity is limited for the Agent and ports 5671 and 5672 cannot be opened outbound to the Azure Service Bus. As a workaround the transport type can be set to AMQP Websockets by adding ;TransportType=AmqpWebSockets to the Azure Service Bus connection string. After this the Azure Service Bus connection will use port 443 for outbound connections.

Inbound connectivity

The Frends Agent operates through Azure Service Bus, which has the connectivity requirements listed above. As such, the server will not receive any inbound connections directly to it for standard operations.

For REST APIs published to your Agent Groups and thus Agents, there will be inbound connectivity for all the API requests, on the ports defined for your Agent. In order for the published API to be accessible, the ports need to allow inbound connections through firewall.

Alternatively for publishing REST APIs, a Gateway Agent can be set up instead. It will act as a gateway and a load balancer for Agents behind it, publishing the APIs without giving direct access to the actual Agents performing the processing. This way the servers hosting the Agents will not require external inbound connectivity, but the API Gateway Agent will require it instead.

Testing connectivity

You can test ports from the machine that is going to be hosting the Frends Agent with either a Powershell command or a Unix command.

Note that if you restrict the outgoing connections, get the correct URL for those tests from the appsettings.secrets.json configuration file.

Setting up an Agent

You should have an Environment and an Agent Group prepared in Frends. You can follow the guide about Creating new Environments & Agent Groups if not.

With the Agent Group set up, you can create the Agent configuration to it. You can follow this guide for more details: How to configure an Agent in Frends.

Installing the Agent

With the Agent set up in Frends, you can start the installation of an Agent to your machine. It is usually a very straightforward process, but you can use the following step-by-step instructions that explain how you can install it.

When installing the cross platform Agents for any platform, you can optionally use additional application settings to override default values. You can learn more about the available settings from Agent application settings.

Installation on Linux machines

First, make sure you have installed .NET and ASP.NET Core on your Linux server. The latest version of Frends requires .NET 8.0. Follow these instructions based on your Linux distribution to install these: https://docs.microsoft.com/en-us/dotnet/core/install/linux.

From the Frends Control Panel, make sure the target Agent Group has Cross-platform option enabled, under Advanced settings.

Then, download the preconfigured binary package for the Agent by selecting Preconfigured Linux binary package from the Agent download options. Unzip the package wherever you want. Ensure it is downloaded in an available directory when running the commands below.

After extraction, open and review file unzipped-agent-dir/secrets/appsettings.secrets.json. You can modify it if required to match your server environment.

With these steps, you are ready to run the deployment script. The script will perform the following tasks:

• Copy Agent files to /opt/frends-agent-linux/

• Create a Daemon service for the Agent called frendsagent

Change your working directory to the Agent directory and run these commands line by line:

sudo chmod 700 ./Deploy-FRENDS-Agent.sh 
sudo ./Deploy-FRENDS-Agent.sh install

After installation, you can control the Agent with the following commands.

Start, stop and check status of the service:

sudo systemctl start frendsagent 
sudo systemctl restart frendsagent 
sudo systemctl stop frendsagent 
sudo systemctl status frendsagent

Checking the Agent logs:

tail -f /var/log/FRENDS/FRENDSAgentService.log

Installation on Windows machines

First, make sure you have installed .NET 8.0 ASP.NET Core Runtime Hosting Bundle and .NET 8 Desktop Runtime x64 or SDK from https://dotnet.microsoft.com/en-us/download/dotnet/8.0.

From the Frends Control Panel, make sure the target Agent Group has Cross-platform option enabled, under Advanced settings. Then, download the Windows installer from the Agent download options.

Unzip the downloaded package into a folder, for example named "Frends Agent Installer". The folder should have the following files:

• appsettings.secrets.json is the dynamically generated Agent configuration settings

• config.json is for custom Agent settings

• Frends.Agent.WindowsInstaller.msi is the installer

After extraction, modify the config.json file to add the Frends user details to it. It is possible the details are already in the json file.

To install the Agent, run Frends.Agent.WindowsInstaller.msi and follow the installer.

When completed, the Agent should become active in the Frends UI.

Windows installation troubleshooting

Error logs for troubleshooting:

• Event Viewer -> Windows Logs -> Application

• C:\Program Files (x86)\HiQ Finland\Frends Agent\logs

Error: .NET v6.0 or later required

If you encounter this error, please make sure you have the correct ASP.NET version. Installation steps can be found in the prerequisites section at the beginning of this article.

Error: Could not find configuration file

If you encounter this error, please make sure you have extracted the contents of the Windows Installer folder into a separate location, and are running the Frends.Agent.WindowsInstaller.msi file from there.

Error: InstallAgentService failed

If you encounter this error, please make sure that the Domain name, username, and password inside the config.json folder are the same as the ones found in Windows Powershell after running the hostname command, and the Local User was created in the previous step.

Installation on Kubernetes

To install Frends Agent on Kubernetes, you need to make sure the target Agent Group has cross platform option enabled. In addition for containerized deployment you need to enable the Allow new Agents to connect to the Agent Group option enabled. Both of these options are enabled from the Frends Control Panel, in Environment and Agent Group settings, under Advanced settings.

Unlike for standard Frends Agent installation, you do not need to configure the Agent in your Frends Tenant beforehand. Enabling the option will allow the Agents to connect to your Agent Group automatically after deployment.

Then, download the configuration file by clicking on the Download Kubernetes configuration link.

The downloaded archive will contain the following files:

• deploy directory. This is the working directory. You should run the kubectl commands detailed in README.md from here. When running the commands ensure you are running them from this directory.

• README.md this file contains kubectl commands, instructions and information specific to your Agent deployment.

• FRENDS-Agent-Deploy.yaml this yaml file defines the deployment and service configuration for your Agent

• DatabaseInitializer.zip used to initialize an SQL database for use as a Shared State Store.

• secrets directory. This contains the appsettings.secrets.json file and the place to copy your optional SSL certificate (pfx). The contents of this directory are used to create Kubernetes Secrets for your deployment.

• appsettings.secrets.json this json file contains application settings specific to your Agent deployment.

To complete the deployment, follow the steps defined in README.md.

In order to configure the Agent for your use case, you can check the configuration options at Agent application settings.

There are multiple different ways to give the application settings to a container.

1. Directly bundle the appsettings.json inside the container image

2. Set the configuration into the container environment variables

3. Pass the configuration as environment variables for Docker or Docker Composer

   • Check here for the docker documentation

   • Here is the documentation for docker-compose

4. You can pass the configuration for Kubernetes either as:

   • environment variables as documented in Kubernetes docs

   • secrets directly from the appsettings.secrets.json file, as explained in the README.md file

Installation on Docker

From the Frends Control Panel, make sure the target Agent Group has Cross-platform option enabled, under Advanced settings.

Then, download the configuration files from the Agent download options by selecting the Configuration only option.

You will also need the current Frends version number from your Frends Tenant, which you can find under the profile menu, on top right corner. The version number might be 6.1.1.2773 as an example.

Alternatively, you can use for example curl command to get the version number, using command like curl https://tenantname.frendsapp.com/api/navigation/getUIVersion.

Use the following command to launch a Docker Container:

docker run -it -v {full local path to config.json}:/app/secrets/appsettings.secrets.json frendsplatform/frends-agent-linux:{FrendsVersion}

Replace the {full local path to config.json} and {FrendsVersion} with the actual path and version value you have. The -v parameter mounts the downloaded local agent config json file in the container under /app/secrets/appsettings.secrets.json.

Actual command might look like the following on Windows OS:

docker run -it -v c:\downloads\downloaded_agent_config:/app/secrets/appsettings.secrets.json frendsplatform/frends-agent-linux:6.1.1.2773

In order to configure the Agent for your use case, you can check the configuration options at Agent application settings.

There are multiple different ways to give the application settings to a container.

1. Directly bundle the appsettings.json inside the container image

2. Set the configuration into the container environment variables

3. Pass the configuration as environment variables for Docker or Docker Composer

   • Check here for the docker documentation

   • Here is the documentation for docker-compose

4. You can pass the configuration for Kubernetes either as:

   • environment variables as documented in Kubernetes docs

   • secrets directly from the appsettings.secrets.json file, as explained in the README.md file

Legacy installation on Windows

In order to perform installation of legacy Frends Agent, make sure the target Agent Group has cross platfrom option disabled. Legacy Agent cannot be installed into a cross platform Agent Group, and vice versa.

With the cross platform option disabled, select Installation package from the download options for the configured Agent. Note that the download options for non-cross platform Agent Groups and Agents are different than if the cross platform option is enabled.

After downloading the Agent, copy the Agent installer package to your chosen server and un-zip the installer package to a temporary location. It's a good practice to archive the Agent installer packaged on the server if you might want to re-install the Agent later, though you can also always download the installer from the Frends Environment View.

The un-zipped installer package should have two files: a config file and the Frends.Agent.Installer.Bundle. Double click the Frends.Agent.Installer.Bundle to start the installation. You can configure the installation location during the process, which by default is set to Program Files folder.

If the installation was successful, you are now done! You have a working Frends Agent installed on your server and you can start deploying and executing integrations with it.

Verifying the Agent is working

After you have installed your Frends Agent you can now see the new Agent in the Environment and Agent Group selector in the Process View. If you select your Environment you should see a message: "No Processes". This means that we can now deploy a Process to the Environment to verify that everything works as it should.

If the Process deployment and activation succeeded, you should see that the Trigger for your Process, in the Triggers column, is highlighted in blue. Hovering the mouse over it will also tell you that the Trigger is active on the listed Agents.

You can also check the deployment directory in the newly installed Frends Agent server, for example on Windows:

C:\Users\{YOUR AGENT USERNAME}\AppData\Local\Frends Technology\Frends Agent\processes

Inside the folder you can see all the integration Processes as well as their versions deployed to the Agent and all of their source code and compiled code that the Agent executes.

You can also monitor your Agent from the Services app on the device the Agent is installed on. In the Status column you can observe whether your Agent is running or not.

Here it is possible to start, pause and stop the Agent. It may take a few minutes for the Agent to stop running.

High Availability & other installation variations

Agents and Agent Groups can be configured in different ways for different kinds of needs.

Multiple Agents in an Agent Group with a shared SQL database

If a central SQL Server or Azure SQL Database instance is available and an Agent Group has a connection string set for it, the Agents will use a shared SQL database called Shared State Store and all Triggers are available in High Availability mode, meaning all connected Agents can execute any Trigger.

This is the most common mode of installing multiple Agents in one Agent Group and should be used in most cases.

Multiple Agents without a shared SQL database

If there's no central database available or the connection string is not set, all the Agents will use a local database for storing configuration information by themselves.

The first deployed Agent in Agent Group will be the "Primary Agent". This Agent will be able to execute all Triggers. Other Agents will be able to run HTTP, API and Service Bus Triggers in the Agent Group. If this mode is selected, Schedule and File Triggers cannot be run in High Availability mode, meaning only the Primary Agent will run those Triggers.

This mode of installation is useful if you do not have a SQL Server but still want to have redundancy and load balancing for HTTP and API Processes.