Installing the Avantra Server

Before you start your installation, please ensure to read the release notes for Avantra 23 and use the latest software versions and patches of Avantra, as described in the Components section.

Installation Notes

The following section is designed to explain some of the common aspects of installing the Avantra solution. Please familiarize yourself with these concepts prior to the software installation.

License

You need a license to run Avantra. Please follow instructions from the Obtaining and Installing the License article to get and install the license, which you will need at the end of the Avantra Server installation process.

Supported Platforms

Please check Avantra Server Components for supported platforms.

Permissions

You must have local administrator permissions (on Microsoft Windows operating systems) or root permissions (on Unix-like operating systems) in order to perform the installation.

Database

Avantra on Microsoft Windows operating systems requires a Microsoft SQL Server as a data store. For product evaluation as well as small-sized installations we recommend installing Microsoft SQL Server 2019 Express Edition. The installation procedure is described in Installing the Microsoft SQL Server. For detailed information on server databases, refer to the Avantra Server Databases article.

If you already have a Microsoft SQL Server installation available ( Microsoft SQL Server 2012 or higher) or you are performing a shared installation, please make sure that you enable local and remote TCP/IP connections.

If you plan to run the Avantra Database on a Microsoft SQL Server hosted on a server separate from other Avantra Server components, please ensure that the Avantra Server components have the necessary permissions to access the Microsoft SQL Server.

Avantra on Unix-like operating systems requires a PostgreSQL data store. The installation is described in {https://support.avantra.com/a/solutions/articles/44001810945?lang=en}.

If you intend to deploy your Avantra Server with a major cloud provider, you may want to consider using a database service such as Amazon Web Services Relational Database Service, Microsoft Azure SQL Database service, or Google Cloud Platform Cloud SQL. For Amazon Web Services and Google Cloud Platform, please make sure to use the PostgreSQL variants of the corresponding services. See also this article.

Installation in a Cluster Environment

As a general recommendation, if you plan to install the Avantra Server in a clustered environment, consider creating two virtual servers (or switching groups): one with the RDBMS (Microsoft SQL Server or PostgreSQL, depending on the operating system) containing the Avantra Database, the other one with Avantra Master and Avantra UI.

Make sure that during the installation process you choose installation locations that switch properly together with the virtual servers.

During the installation of the Avantra Server, you have the option to stage the Avantra Database on a remotely installed RDBMS.

Security Considerations

Communication between Avantra Agents and Avantra Server is encrypted using HTTPS.

We recommend that communication between Web browsers and the Avantra UI is also encrypted using HTTPS. If you plan to use HTTPS communication, please read these knowledge base articles: UI SSL Issues and Use CA signed Certificate for HTTPS in the UI.

Running the UI on port 80/443 (Unix only)

On Unix-based systems, port 80 and port 443 are protected; typically only the superuser root can open them. For security reasons, it is not desirable to run the Avantra Server as root. By default, Avantra UI uses ports 8080 and 8443. If you wish to have users access Avantra UI using the standard HTTP/HTTPS ports, we recommend installing Avantra Server as a non-root user and to redirect ports 80 and 443 to 8080 and 8443 respectively using the operating system’s means.

On Linux, you may use iptables (or ipchains).

Please consult your operating system documentation.

If you run the Avantra Server installer as root, you can configure the Avantra Server and Avantra UI to use the standard ports 80 and 443.

If you are using one of the major cloud platforms, there are services available to do the host and port mapping for you, like a load balancer, endpoint services, etc. There is usually no need to run the services as root user in this scenario.

Different Unix flavors commands

The file paths and directory names used within this documentation, as well as the syntax used in operating system files (especially for the crontab) may vary from system to system, or even between different releases or distributions of the same operating system. For further information, please refer to your operating system documentation, e.g. man cron, man crontab, and others, or ask your operating system administrator.

Supported Installation Methods

Avantra can be installed using multiple methods. We recommend using a Linux based operating system with a PostgreSQL database and provide a quick installation method to get you started quickly on a cloud virtual machine. After either installation method, please follow the Post Installation Steps

Using the Avantra Quick Installer

For ease of initial setup, we provide an automated installation option for new systems ONLY on linux. This option will install a single node installation of the latest Avantra server along with all the dependencies, including PostgreSQL with an Avantra Agent pre-installed on the local machine. If you wish to deviate from this installation we recommand a manual installation following the installation guides below.

The installation will take approximately 5-10 minutes and is supported on the following OS types:

  • SUSE Linux 15 sp3 and above

  • Red Hat Enterprise Linux 7 and 8

  • Ubuntu 20.04

To use this method, simply visit the download site at https://downloads.avantra.com and copy the single quick install command from the download center.

The command must be run with a sudo-capable or root user.

Manual installation

For installations that would like to customise dependencies, choose a specific database or cloud database service, a manual installation needs to be followed.

Follow the appropriate guide for either Unix-like (Linux) or Microsoft Windows installations.

Installation on Kubernetes

From Avantra 23.0, we support installation of Avantra on a Kubernetes cluster in specific circumstances.

Please follow the following installation instructions.

Customers who wish to use this method of installation should reach out to Avantra Support for access.

Post Installation Steps

Obtaining and Installing the License

To run Avantra, you need a license. Until you have received a valid license, you can run Avantra in DEMO mode with a single Avantra Agent only.

At the end of the installation, you will switch to the Avantra UI web login page. Use the application root user and password created during the installation process to log in.

  1. Select Administration  Licenses from the Avantra UI top-level menu. The Licenses page opens.

  2. Click the Request / Install Avantra License button and then click Request License. A dialog box will open showing your Activation ID and some fields to fill in the number of licenses required. Press Continue.

  3. An email to support@avantra.com will be opened using the email program of your system with the data entered in the form. Please feel free to modify this email and to add any notes, then submit the mail.

  4. In response to your query, you will receive an e-mail or log entry in your support ticket with the license key. Please return to the Licenses page (Administration  Licenses) and click Request / Install Avantra License. Then copy and paste the license key including the lines marked as -----BEGIN/END XLIC BLOCK----- to the corresponding text box and press OK.

  5. A message appears that the license was installed. Verify the Status and Status Message are Ok.

Avantra UI Post-Installation Steps

In order to automate the setup as much as possible, the Avantra Master tries to determine the Fully Qualified Domain Name of the host it is actually running. This information is used for communication between the Avantra Server components, as well as for communication between the Avantra Agents and the Avantra Server.

To verify if the settings are correct, follow these steps:

Procedure: Verify the Host Settings

  1. Select About from the top-level menu.

  2. Click on Avantra Master. Verify the values of Masterhost, Masterport, and Bind Address.

    • The Masterhost should contain a host name, Fully Qualified Domain Name, or IP address of the Avantra Server that can be connected to from all, or at least most, Avantra Agents.

    • The Masterport can be used to configure a different listening port of the Avantra Master. There is usually no need to change this setting unless there is another application already using the default port 9050.

      If you chose a different communication port during installation, you can later configure an HTTPS port or HTTP → HTTPS redirection, which is what we recommend. The connection parameters can be configured in the xangui.cfg file.

    • The Bind Address can be used to restrict the listening port of the Avantra Master to certain IP addresses in case the Avantra Server has multiple network interfaces. The value 0.0.0.0 means the Avantra Master is listening on all network interfaces.

      Starting with Avantra Version 20.11.4, you can restrict Avantra UI listening on ports 8080 and 8443 to bind to a specific IP address. To configure the bind address, use the xangui.cfg file and add the appropriate line, for example, bindAddress=127.0.0.1.

      Click on Avantra UI. Verify the value Avantra UI host.

  3. If the values determined automatically are not suitable for you:

Preparing the Avantra Agent Deployment

You can use the Avantra Master to simplify the initial deployment of the Avantra Agent to each system.

This may be useful to avoid downloading the files from our website over and over again for every Server you install the Avantra Agent on. Instead, you can use a browser or tool like wget or curl to retrieve the files directly from your Avantra Server.

Download the following files from the Support menu of avantra.com:

  • agent-23.n.bin from the AGENT RELEASE 23.n section

  • agent-23.n-setup.exe from the AGENT RELEASE 23.n section

  • transports-for-avantra-23.zip from the CONTRIB RELEASE 23.0 section

Save them to the AgentUpdate directory on the Avantra Server, located at %ProgramFiles%\AgentUpdate (on Microsoft Windows operating systems) or /avantra/AgentUpdate (on Unix-like operating systems).

You can access the packages then using the following statements from within your own network:

$ wget http://avantra-server:9050/AgentUpdate/agent-23.n.bin

or

$ curl http://youravantra-server:9050/AgentUpdate/transports-for-avantra-23.zip > transports-for-avantra-23.zip