# 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)

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

| Avantra previously supported PostgreSQL 9.6 and 11 however these are now no longer supported by PostgreSQL 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-24.0-[os].bin` from the SERVER RELEASE 24.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-24.0-[os].bin

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

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

   Otherwise run

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