Installing the Avantra Server

Before you start your installation, please ensure to read the release notes for Avantra 20.5. Please also ensure you 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 2008 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 Installing the PostgreSQL RDBMS.

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); AIX provides similar means.

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 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.

Installing on Microsoft Windows operating systems

This section describes how to actually install the Avantra Server.

We recommend to install the Avantra Master and Avantra UI on the same host, although the installer allows you to install them separately. We advise contacting the Avantra Support team if you plan to install the Avantra Master and Avantra UI on separate hosts.

If there are any issues during the installation and you need to do the root cause analysis, you can find the log files in %TEMP%/Avantra Installation Logs.

Installing the 64-bit Java Runtime Environment (on Microsoft Windows operating systems)

The Avantra Server only runs on a 64-bit Microsoft Windows operating system and requires the 64-bit Java 8, 9, or 10 Runtime Environment.

If you do not you have a suitable 64-bit Java 8, 9, or 10 Runtime Environment installed, see Avantra and Java for more information.

Installing the Microsoft SQL Server

You can skip this step if you already have installed a Microsoft SQL Server or use a remote one. In this example the Express Edition is installed.

Perform these steps on the server supposed to host the Avantra Database, either the Avantra Server or a dedicated database host.

Procedure: Installing Microsoft SQL Server Express Edition

Download the latest Microsoft SQL Server Express Edition (e.g. Microsoft SQL Server 2019 Express Edition) from this location and save file locally, e.g. to C:\Downloads.
Open the recently downloaded file (e.g. SQLServer2019-SSEI-Expr.exe):
1. Choose Download Media.
2. Choose Express Core and – if desired – change the download location to e.g. C:\Downloads.
3. Push the Download button.
4. Push the Close button.
Open a command prompt and switch to the directory chosen in Step 2b.
Run the following command:

SQLEXPR_x64_ENU.exe /ACTION=Install /AddCurrentUserAsSQLAdmin
/FEATURES=SQL,Tools /IAcceptSQLServerLicenseTerms /QUIETSIMPLE
/SQLSVCACCOUNT=SYSTEM /SQLSYSADMINACCOUNTS=SYSTEM /TCPENABLED=1
/INSTANCENAME=MSSQLSERVER /SQLSVCSTARTUPTYPE=Automatic
/SECURITYMODE=SQL /SAPWD=+XandriA123456789!

Please adapt the value for SAPWD to set the default password for the sa login.

This procedure describes the most convenient way to install Microsoft SQL Server.

The only requirements Avantra has are the following: a user (either Windows user or an SQL user) has the permission to be the owner of an Avantra Database; access the database using TCP/IP. You should be familiar with the database security models and policies of your organization and we highly recommend adapting the command line call above accordingly or perform a plain installation and change the settings afterwards using SQL Server Management Studio (SSMS) and/or SQL Server Configuration Manager.

For more information, refer to the SQL Server Technical Documentation.

For an explanation of the command line options, refer to Install SQL Server from the Command Prompt.

For more information on how to schedule and automate backups for the Microsoft SQL Server Express Edition, refer to How to schedule and automate backups of SQL Server databases in SQL Server Express

Verify TCP/IP Settings of Microsoft SQL Server

You can skip this section if you have already performed all the steps in Installing the Microsoft SQL Server.

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

Open the SQL Server Configuration Manager, choose SQL Server Network Connections Protocols for [instance_name] and set the Status for TCP/IP to Enabled.

Running the Avantra Server Installer

Procedure: Running the Avantra Server Installer

Download avantra-server-20.5.0-win64.exe from the SERVER RELEASE 20.5.0 section at the Support menu of avantra.com.
Open the installer, push Next on the welcome screen and accept the license using the I agree option on the license screen.
You are asked to install either the Avantra Master, the UI, or both. Usually you will leave the default and install both. Push Next to continue.
Choose an appropriate installation location and push Next.
Choose the ports for incoming HTTP and or HTTPS connections of the web UI. You may push the Verify Ports button in order to check if the ports are free. Press Next.
Verify the Windows Firewall configuration rules that will be added to your system. Press Next to proceed.
Choose the (Windows) user to run the Windows services as. If you use Windows Authentication for the Microsoft SQL Server (which is the default in Step 4 of the Procedure: Installing Microsoft SQL Server Express Edition), make sure you use the same user here as for the Microsoft SQL Server.

If you did not change the command in Step 4 of Procedure: Installing Microsoft SQL Server Express Edition, leave it to the default LocalSystem here. If your Microsoft SQL Server is running with a different user, fill in the same user. Press Next to proceed.
Push Install.
On the final screen, make sure you have checked Install UI and Master and push Finish.

Staging the Avantra Database (on Microsoft Windows operating systems)

Open your browser at http(s)://localhost:[port] (with the port as defined above)
Choose Microsoft SQL Server and push Next.
The local server is searched for SQL Server instances. Select an appropriate value from the drop-down list (there will be usually only one). If you need to connect to a different Microsoft SQL Server, fill in Host / Port and Instance Name. Push Next.
Choose Windows Authentication if you want to access the Microsoft SQL Server using this security model. Otherwise define an SQL User / Password. Push Next.
Define a name for the database. You will usually leave this to the default value xandria. Push the Create Database & Check button.
Define the application root user. Fill in values for Root user name and Root user password and push the Create button.

Note down these credentials carefully and keep them at hand. For the time being, this will be the only way to access the application!
Push Save and switch to Avantra UI to finish the installation.

Installing on Unix-like operating systems

This section describes how to install the Avantra Server on a Unix-like operating system.

Preparing the Installation

You have to be familiar with the following topics to perform this installation:

Adding users and groups
Using package managers
Managing the cron facility
Creating file systems (if desired)

Perform these steps as user root:

Operating system user and group

If you intend to run the Avantra Server with one of the major cloud providers, you can use the standard user of the installation image and work with the sudo command.

Create an operating system group xandria.
Create an operating system user xandria. Add this user to the xandria group and create a home directory /home/xandria. We recommend to use a sh-like login shell, like bash or ksh.

Create a File System

Unless completed already, create a file system /syslink of at least 30 GB size, or create a directory somewhere in an existing file system (having at least the required free space) and make a symbolic link /syslink to the newly created directory.
Change the ownership of the /syslink directory to the user and group xandria:

root$ chown -R xandria:xandria /syslink

Installing the 64-bit Java Runtime Environment (on Unix-like operating systems)

Unless you have a 64-bit Java Runtime Environment installed (8, 9, or 10), you now have to do so.

On Unix-like operating systems you can usually install the 64-bit Java 8, 9, or 10 Runtime Environment using the standard package management for the operating system. This is the recommended way since it usually also provides ways for automatic updates, etc.

If you do not want to use a package manager, see Avantra and Java.

Installing the PostgreSQL RDBMS

In order to make the installation easier, we provide a compiled and packaged version of PostgreSQL 9.6.4. We did not make any changes to the source files.

If you intend to use a PostgreSQL installation available through the package management of your operating system refer to this document: Using a standard PostgreSQL Installation with Avantra.

Perform the following steps as user xandria:

Procedure: Running the PostgreSQL installer

Download xandriadb-pgsql-9.6.4-[os].bin from the CONTRIB RELEASE 20.5.0 section at the Support menu of avantra.com and save it to /syslink.

Make sure the file is executable:
```
xandria$ chmod 755 xandriadb-pgsql-9.6.4-[os].bin
```

Run the installer:

xandria$ ./xandriadb-pgsql-9.6.4-[os].bin

At the end of the installation you will be asked to create a so called database role. A role in this case is PostgreSQL terminology for a database user. You will use this user within Avantra to access the database (in Staging the Avantra Database on Unix). Choose the name and password carefully and make sure you remember it.

You cannot use the name xandria here, if that is the operating system user you are running the installer with. This user is automatically created as a built-in database administrator, but only has access on the command line. So it cannot be used by Avantra.

There is a small script xandria`dump.sh_ provided in `/syslink/xandriadb/backup/bin that you can use to perform backup. You may use the cron facility to schedule these backups.

As user xandria, edit the crontab files and add lines for the backup:

xandria$ crontab -e
# Xandria Backup
30 23 * * * /syslink/xandriadb/backup/bin/xandria_dump.sh --dbname=xandria > /dev/null 2>&1
50 23 * * * /syslink/xandriadb/backup/bin/xandria_dump.sh --dbname=GLOBALS > /dev/null 2>&1

Installing the Avantra Server Components

Perform the following steps as user xandria (or as user root if you plan to use ports 80 and/or 443 as described in item Running the UI on port 80/443 of Installation Notes):

If you are installing on Redhat 8 or CentOS 8, please install the libnsl`package: `sudo dnf install libnsl

Procedure: Running the Avantra Server installer:

Download xandria-server-20.5.0-[os].bin from the SERVER RELEASE 20.5.0 section at the Support menu of avantra.com and save it to /syslink.

Make sure the file is executable:
```
xandria$ chmod 755 avantra-server-20.5.0-[os].bin
```
If the Java Runtime Environment (8, 9, or 10) is installed and on your path, run
```
xandria$ ./avantra-server-20.5.0-[os].bin
```
Otherwise run
```
xandria$ ./avantra-server-20.5.0-[os].bin -- --jvm=[path_to_java_executable]
```
where [path_to_java_executable] the absolute path of the java executable.

NOTE: Yes, it’s really -- first and then --jvm.
You will be asked to define the HTTP and HTTPS ports for Avantra UI to use. We recommend you choose to redirect the HTTP port to the HTTPS port and use HTTPS by default.
Once finished, the installer automatically starts Avantra Master and Avantra UI via the web user interface.

Staging the Avantra Database on Unix

Open your browser at https://[avantra_server]:[port] (with port as defined above)
Choose PostgreSQL and push Next.
Fill in the name of your Avantra Server into Host / Port. You do not need to define the port. Push Next.
Fill in the user and password you defined in Step 3 of Procedure: Running the PostgreSQL installer into SQL User / Password. Push Next.
Define a name for the database. You will usually leave this to the default value xandria. Push the Create Database & Check button.
Define the application root user. Fill in values for Root user name and Root user password and push the Create button.

Note down these credentials carefully and keep them at hand. For the time being, this will be the only way to access the application!
Push Save and switch to Avantra UI to finish the installation.

Including Avantra Daemons in the system init process

In order to automatically start the Avantra Server components at the system’s boot up, and to terminate them properly at shutdown, you may want to include them in your system initialization process. Please refer to your system documentation.

Start the different components in the following order:

For the shutdown procedure use the reverse order.

Starting and Stopping Avantra Server components manually

You may use the following commands to stop Avantra Server components manually. Use that order to stop the whole system:

Avantra UI: /syslink/xangui/rc.xangui stop
Avantra Master: /syslink/master/rc.master stop
Avantra Database: /syslink/xandriadb/rc.xandriadb stop

You may use the following commands to start Avantra Server components manually. Use that order to start the whole system:

Avantra Database: /syslink/xandriadb/rc.xandriadb start
Avantra Master: /syslink/master/rc.master start
Avantra UI: /syslink/xangui/rc.xangui start

Post Installation Steps

Obtaining and Installing the License

In order 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 switched to the Avantra UI web login page. Use the application root user and password created during the installation process to login.

Select Administration Licenses from the Avantra UI top-level menu. The Licenses page opens.
Click the Request / Install Xandria 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.
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.
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 Xandria 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.
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 that 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.

In order to verify that these settings are correct perform the following steps:

Procedure: Verify the Host Settings

Select About from the top-level menu.
Click on Xandria Master. Verify the values of Masterhost, Masterport, and Bind Address.
- The Masterhost should contain a host name or 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.
- 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.
  
  Click on Avantra UI. Verify the value Avantra UI host.
If the values determined automatically are not suitable for you:
- Push the button.
- Enter the appropriate value and push the Apply button.
- Restart the Avantra Master and/or Avantra UI.

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 web site 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-20.5.n.bin from the AGENT RELEASE 20.5.n section (or avantra-agent-20.5.n-[o].[p].x86_64.rpm if you intend to install agents on Linux)
`agent-20.5.n-setup.exe`_ from the AGENT RELEASE 20.5.n section
transports-for-avantra-20.5.zip from the CONTRIB RELEASE 20.5.0 section

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

If you want to use the RPM, download the corresponding package instead, in conjunction with the signing key.

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

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

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