Installing on Linux

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

For our quick installer, a one-line Avantra Server command to install our server, all necessary dependencies (including PostgreSQL) and a local Avantra Agent, please follow these instructions.

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.

  1. Create an operating system group avantra.

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

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

  2. 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 15.x

  • PostgreSQL 14.x

  • PostgreSQL 13.x

  • PostgreSQL 12.x

  • PostgreSQL 11.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.

See also the pg_hba.conf file.

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 4. The final step is to make sure that there is no host-based firewall or SE Linux configuration on the PosgreSQL server preventing the connection from the Avantra server. The same is true for any network firewall. This is something that you definitely need to take care of if you use cloud services.

Previous versions of Avantra (prior to and incl. 20.5) included an optional pre-configured PostgreSQL installer to simplify installation in demo and non-production environments. Please note that this package is no longer supported and will not be maintained. We highly recommend switching to a package-manager and supported version of PostgreSQL to ensure you are receiving regular updates for your database installation. For guidance on how to migrate to another PostgreSQL installation, please see this solution document.

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 and DejaVu fonts 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:

  1. Download avantra-server-23.0-[os].bin from the SERVER RELEASE 23.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-23.0-[os].bin

  2. If the Java Runtime Environment 8 is installed and on your path, run

    avantra$ ./avantra-server-23.0-[os].bin

    Otherwise run

    avantra$ ./avantra-server-23.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.

  3. You will be asked to define the HTTP and HTTPS ports for Avantra WebUI to use. We recommend you choose to redirect the HTTP port to the HTTPS port and use HTTPS by default.

  4. Once finished, the installer automatically starts Avantra Server and Avantra WebUI via the web user interface.

A number of command line flags are available to influence the installer.

The flags must follow a -- after the installer name e.g. ./avantra-server-23.0.3.bin — --no-start --silent
Installer Flag Purpose

--jvm, -j

Specify the location of the Java virtual machine

--no-start

Do not start services after installation or upgrade

--jvmargs

Arguments to be passed to the underlying JVM

--skip-xangui

Do not install/upgrade the UI component

--skip-master

Do not install/upgrade the server component

--silent

Do not prompt the user for any input

-C xangui.port=8080

Set the UI HTTP port to 8080

-C xangui.sslPort=8443

Set the UI HTTPS port to 8443

-C xangui.redirectHttpToHttps=yes

Redirect the HTTP port to HTTPS

-C xangui.keyStorePath=/path/file.ks

The path to the keystore where the UI certificate lives

-C xangui.keyStorePassword=trustMe123

The password for the keystore

-C xangui.trustStorePath=/path/file.ts

The path to the keystore where the truststore lives

-C xangui.trustStorePassword=trustMe123

The password for the truststore

-C xangui.certAlias=certificateAliasName

The alias for the UI certificate in the keystore

Staging the Avantra Database on Unix

  1. Open your browser at https://[avantra_server]:[port] (with port as defined above)

  2. Choose PostgreSQL and push Next.

  3. Fill in the name of your Avantra Server into Host / Port. You do not need to define the port. Push Next.

  4. Fill in the user and password you defined in Step 3 of Procedure: Running the PostgreSQL installer into SQL User / Password. Push Next.

  5. Define a name for the database. You will usually leave this to the default value avantra. Push the Create Database & Check button.

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

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

  1. Avantra Database

  2. Avantra Server

  3. Avantra WebUI

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 WebUI

/avantra/xangui/rc.xangui stop

Avantra Server

/avantra/master/rc.master stop

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

Avantra Server

/avantra/master/rc.master start

Avantra WebUI

/avantra/xangui/rc.xangui start

Previously (version 20.5 and below), Avantra supplied a pre-packaged PostgreSQL 9.6 installation. Please note that this PostgreSQL version and its use with Avantra are unsupported as this version of PostgreSQL is out of support.

We recommend migrating to a package-manager provided installation of PostgreSQL. Customers still using this version for test and demo purposes can use the commands below.

To stop the system:

Avantra WebUI

/avantra/xangui/rc.xangui stop

Avantra Server

/avantra/master/rc.master stop

Avantra Database

/avantra/xandriadb/rc.xandriadb stop

To start the system:

Avantra Database

/avantra/xandriadb/rc.xandriadb start

Avantra Server

/avantra/master/rc.master start

Avantra WebUI

/avantra/xangui/rc.xangui start