Installing the Avantra Server

Before you start your installation, please ensure to read the release notes for Avantra 21.11 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 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).

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.

Installing on Microsoft Windows operating systems

This section describes how to actually install the Avantra Server.

We recommend installing 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 Runtime Environment.

If you do not have a suitable 64-bit Java 8 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 the 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 2012 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-21.11.0-win64.exe from the SERVER RELEASE 21.11.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 avantra. 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 avantra.
Create an operating system user avantra. Add this user to the avantra group and create a home directory /home/avantra. We recommend using a sh-like login shell, like bash or ksh.

Create a File System

Unless completed already, create a file system /avantra 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 /avantra to the newly-created directory.
Change the ownership of the /avantra directory to the user and group avantra:

root$ chown -R avantra:avantra /avantra

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

Unless you have a 64-bit Java 8 Runtime Environment installed, you now have to do so.

On Unix-like operating systems you can usually install the 64-bit Java 8 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

PostgreSQL is included in various Linux distributions, and the PostgreSQL project describes many ways to install the RDBMS in a way that integrates well with the Linux package management process. The big advantage of these installations is that they automatically cover patch updates. Therefore, our best practice recommendation is to use your own OS package manager in line with your corporate IT policies and guidance.

Furthermore, all major cloud providers offer PostgreSQL as a service. Our Avantra for AWS solution leverages Amazon RDS for PostgreSQL in the same way that Avantra for GCP uses Cloud SQL for PostgreSQL. Microsoft Azure offers Azure Database for PostgreSQL, and AWS offers a PostgreSQL-compatible version of Amazon Aurora. All of these different options - Linux packages and cloud services - work great with Avantra Server if you keep a few considerations in mind.

The Avantra Server on Unix supports the following PostgreSQL versions:

PostgreSQL 13.x
PostgreSQL 12.x
PostgreSQL 11.x
PostgreSQL 10.x

Avantra previously supported PostgreSQL 9.6 however this is now no longer supported by PostgreSQL and is no longer recommended for use with Avantra.

When deciding to use a standard package, make sure it is one of the supported versions. Even widely used Linux distributions may offer relatively old (and therefore unsupported) versions of PostgreSQL.

Procedure: Configuring PostgreSQL for Avantra Server

Step 1. Create a database user that has permissions to create databases for the Avantra Setup to run. If you have installed one of the standard packages, initialized and started the database cluster, you can do so with the following command:

sudo -u postgres createuser --interactive --createdb --no-createrole --no-superuser --pwprompt

If you are using one of the cloud services, please refer to the related documentation.

Step 2. By default, PostgreSQL only listens on the loopback (or localhost) address. If your Avantra Server is not installed on the same server as the PostgreSQL database, you need to configure the PostgreSQL listener to accept traffic on all network interfaces. This can be done in the postgresql.conf file.

Use the following command to determine the location of the postgresql.conf file:

sudo -u postgres psql -c "show config_file"

Then change the line containing the listen_address statement to:

listen_addresses = '*'       # what IP address(es) to listen on;
                             # comma-separated list of addresses;
                             # defaults to 'localhost'; use '*' for all
                             # (change requires restart)

Make sure you restart PostgreSQL after these changes. If you use one of the cloud services, there is most likely nothing to do for you.

Step 3. By default, PostgreSQL restricts access to the listener by means of host-based access control files to local connections only. If your Avantra Server is not installed on the same server as the PostgreSQL database, you need to configure the PostgreSQL listener to allow connections from the Avantra Server. This is done in the pg_hba.conf file.

Use the following command to determine the location of the pg_hba.conf file:

sudo -u postgres psql -c "show hba_file"

Then append the line host all all <address> md5 with <address> the IP address of the Avantra Server (or the network it is located in) in CIDR notation.

Installing the Avantra Server Components

Perform the following steps as user avantra (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):

Make sure to install the Fontconfig package according to your Linux distribution. For Redhat 8 or CentOS 8, please also install the libnsl`package: `sudo dnf install libnsl

Procedure: Running the Avantra Server installer:

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

Make sure the file is executable:
```
avantra$ chmod 755 avantra-server-21.11.0-[os].bin
```
If the Java Runtime Environment 8 is installed and on your path, run
```
avantra$ ./avantra-server-21.11.0-[os].bin
```
Otherwise run
```
avantra$ ./avantra-server-21.11.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 avantra. 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

To automatically start the Avantra Server components at the system’s boot up and 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: /avantra/xangui/rc.xangui stop
Avantra Master: /avantra/master/rc.master stop
Avantra Database: /avantra/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: /avantra/xandriadb/rc.xandriadb start
Avantra Master: /avantra/master/rc.master start
Avantra UI: /avantra/xangui/rc.xangui start

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.

Select Administration Licenses from the Avantra UI top-level menu. The Licenses page opens.
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.
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 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.
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

Select About from the top-level menu.

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.

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 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-21.11.n.bin from the AGENT RELEASE 21.11.n section
agent-21.11.n-setup.exe from the AGENT RELEASE 21.11.n section
transports-for-avantra-21.11.zip from the CONTRIB RELEASE 21.11.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-21.11.n.bin

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