Linux manual installation

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

tip

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

Preparing the installation

warning

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

tip

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)

The Avantra Server requires the 64-bit Java 25 Runtime Environment. On Unix-like operating systems you can usually install this using the standard package management for the operating system, for example dnf install java-25 on RHEL-based distributions. This is the recommended way since it usually also provides ways for automatic updates, etc.

note

On some distributions (for example RHEL 10), the default OS package for java installs an older major version (such as Java 21) rather than Java 25. Explicitly specify the Java 25 package, for example dnf install java-25, rather than relying on the distribution's default java package alias.

If you do not want to use a package manager, see Java Runtime Environment.

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 18.x
• PostgreSQL 17.x
• PostgreSQL 16.x
• PostgreSQL 15.x
• PostgreSQL 14.x

When deciding to use a standard package, make sure it's one of the supported versions. Even widely used Linux distributions may offer relatively old (and therefore unsupported) versions of PostgreSQL. PostgreSQL 14 is the minimum; for the longest support window, we recommend PostgreSQL 15 or 16 as a practical minimum, and ideally 17 or 18. See the PostgreSQL versioning policy for end-of-life dates.

Upgrading PostgreSQL major versions

When you move to a newer PostgreSQL major version, follow the Upgrading a PostgreSQL Cluster procedure, then stop, disable, and remove the old version. If the old version is left in place, it can start first after a reboot and claim the port before the new version, so Avantra connects to the old database and silently serves out-of-date data. Confirm the upgraded version is the one answering on the port in your database.cfg, for example by running SELECT version(); against it.

Configuring PostgreSQL for Avantra Server

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, refer to the related documentation.

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.

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> scram-sha-256 with <address> the IP address of the Avantra Server (or the network it's located in) in CIDR notation.

See also the pg_hba.conf file.

Make sure you restart or reload PostgreSQL after these changes, for example sudo systemctl reload postgresql (the exact command may vary by distribution and setup). If you use one of the cloud services, there is most likely nothing to do for you.

4. The final 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.

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 (Unix only):

note

Make sure to install the Fontconfig and DejaVu fonts package according to your Linux distribution. For RedHat 8 or CentOS 8, install the libnslpackage: sudo dnf install libnsl

Running the Avantra Server installer

1. Download avantra-server-26-[os].bin for release 26 from the Customer Hub and save it to /avantra.
   Make sure the file is executable avantra$ chmod 755 avantra-server-26-[os].bin.
2. If the Java 25 Runtime Environment is installed and on your path, run avantra$ ./avantra-server-26-[os].bin.
   Otherwise run avantra$ ./avantra-server-26-[os].bin -- --jvm=[path_to_java_executable], where [path_to_java_executable] the absolute path of the java executable.
3. You will be asked to define the HTTPS ports for Avantra UI to use.
4. Once finished, the installer automatically starts Avantra Server and Avantra UI via the web user interface.

note

A XANGUI.cfg explicitly needs to specify HTTP is enabled to enable HTTP access. However, we do not recommend using HTTP for production environments.

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

note

The flags must follow a -- after the installer name e.g. ./avantra-server-26.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
-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 Click Next.
3. Fill in the name of your Avantra Server into Host/Port. You do not need to define the port. Click Next.
4. Fill in the user and password you defined in Step 3 of Running the Avantra Installer into SQL User/Password. Click Next.
5. Define a name for the database. You will usually leave this to the default value avantra. Click Create Database & Check.
6. Define the application root user. Fill in values for Root user name and Root user password and click Create button.

caution

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. Click 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. Refer to your system documentation.

Start the different components in the following order:

1. Avantra Database
2. Avantra Server
3. Avantra UI

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 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 UI: /avantra/xangui/rc.xangui start