Written for Frends version 5.7.
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.
This guide will give you an overview of how to configure the Agent and what the prerequisites for it are. You can checkout this article for technical information about the Agent.
Installation Variations
Guidance on installation variations such as a HA Environment is found in this article.
Prerequisites
You will need the following prerequisites to follow this guide:
You will need the following prerequisites to follow this guide:
Admin access to your Frends Tenant to access the Environment View
A server or system that you have Admin access to with the following requirements:
Any Windows 10/11 based system or a Windows Server 2019 or later, or an Ubuntu Server 22.04 LTS or newer.
A Cross Platform Agent requires .NET 8.0
A Legacy Agent requires .NET framework 4.7.2.
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.
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.
It is usually better to have two Frends Agents with less capable hardware than one with powerful hardware. See Agent Installation Variations for further information.
Outbound internet access. Please see Outbound Connectivity for details on how to set up your firewall.
(Optional) The server should have a designated name using any DNS-service.
(Optional) The server should have a valid SSL certificate installed if you want to publish APIs from the server with a valid SSL certificate.
Outbound Connectivity
Frends 5.7 and later requires outbound access to the Frends UI: <tenant>.frendsapp.com on port 443.
In addition all Frends versions require internet access to the Azure service bus. It is usually achieved through port 443 (for HTTPS), 5671, and 5672 (you can learn more about the Azure Service Bus here). As the IP addresses of the Azure services may change, these have to be opened without IP restrictions.
Alternatively if outbound access is being limited for the Agent, those ports 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.
Frends 5.3 and earlier also requires port 80 to be open towards the Azure Service Bus.
Testing Connectivity
You can test ports from the machine that is going to be hosting the Frends Agent with either a Powershell command:
tnc yourtenant-frends-bus.servicebus.windows.net -Port port
Replace yourtenant with your Frends tenant name. You can find it by going to your Frends webpage and looking at the URL, which is in the form tenant.frendsapp.com
Replace port with the desired port you wish to check
or a Unix command:
nc -zv yourtenant-frends-bus.servicebus.windows.net 443 9350-9354 5671-5672.
where yourtenant-frends-bus.servicebus.windows.net is the servicebus URL of your tenant. The correct URL value can be found from the appsettings.secrets.json configuration file on the AzureServiceBusSasTokenConfigurator.Endpoint property. Remember to change the protocol from "sb" to "https".
Note that if you restrict the outgoing connections, get the correct URL for those tests from the appsettings.secrets.json configuration file.
Best Practices
High Availability
For critical workloads we recommend setting up a High Availability Environment. To learn more about it, and other installation variations, please refer to this article.
To actually set up a HA Environment, you need to set up a Load Balancer and an Agent Store before setting up Agents.
Naming
Name your Environments with descriptions of the Environments' functions, such as Development, Test, Production, PartnerNetworkOne and PartnerNetworkTwo. Environment names needs to unique.
Name your Agent Groups using the different Agents' deployment strategies as a basis inside each Environment, for example inside the Production Environment there may be three Agent Groups; Internal, Public Cloud and Hybrid. Agent Group names need to be unique even between Environments.
Name your individual Agents with a reference to the server the Agent is installed on or even the server name or IP address itself. The Agent name needs to be unique within an Agent Group.
Setting up your Environment
Before installing your on-premise Agent for on-premise integration executions or hybrid integration solutions you will need to set up an Environment in the Frends Environment View.
Access the Environment View from the top menu and select the Environment, for example Development, Test or Production, that you want to install the Agent to. You can do this by simply opening up the Environment View and selecting the Environment from the menu. Alternatively you can also create a new Environment to install your Agent in.
Setting up an Agent Group
After selecting the desired Environment click on the "+ New Agent group" button and give your Agent Group a unique name that will distinguish it from other Agent Groups within the same Environment. A good practice is to use a logical name such as "LocalDataCenter" or "PrivateCloudByISP" etc.
In "Advanced settings", make sure to enable or disable the "Cross platform" option depending on whether you are installing a cross platform agent or not.
You can see descriptions of other settings here.
Setting up an Agent
After creating the Agent Group click on the "+ New Agent" button to start the configuration process for your new Agent.
You need to give at least the name and credentials of the user that is used by the Agent. It is recommended to follow these instructions if you are at all unsure about the details given to the Agent.
When installing a Cross-Platform Agent you can also override settings with Application Settings.
Installing the Agent
After that you can install the Agent. Usually, it is a very straight forward process, but you can use the following step-by-step instructions that explain how you can install it.
Cross-Platform Frends Agent on Linux
Cross-Platform Frends Agent on Windows
Cross-Platform Frends Agent on Kubernetes
Cross-Platform Frends Agent on Docker
Legacy Frends Agent on Windows.
Verifying the Agent is functioning
After you have successfully installed your Frends Agent you can now see the newly installed Agent in the Environment and Agent Group selector in the Process View. If you select your newly created Environment, you should see a message: "No Processes". This means that we can now deploy a Process to our newly created Environment to verify that everything works as it should:
You should be able to see the Process update and the Process Trigger activate in the new Environment if the deployment was successful.
You can also check the deployment directory in the newly installed Frends Agent server in the folder, for example, on Windows:
C:\Users\{YOUR AGENT USERNAME}\AppData\Local\HiQ Finland\Frends Agent\processesInside 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.
Note: The Frends service user must be in local admin group on the server.