Skip to main content

# 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, please 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)​

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 the Avantra Knowledge Base article Avantra and 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 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.

### 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, please 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> md5` 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 PostgreSQL after these changes. 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.

note

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 the Avantra Knowledge Base article How to migrate Avantra DB to a standard PostgreSQL installation.

## 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, please also install the `libnsl`package: `sudo dnf install libnsl`

### Running the Avantra Server installer​

1. `avantra-server-25.0.n-[os].bin` from the SERVER RELEASE 25 section at [download URL] and save it to `/avantra`.
   Make sure the file is executable `avantra$ chmod 755 avantra-server-25.0.n-[os].bin`.
2. If the Java Runtime Environment 8 is installed and on your path, run `avantra$ ./avantra-server-25.0.n-[os].bin`.
   Otherwise run `avantra$ ./avantra-server-25.0.n-[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 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.
4. Once finished, the installer automatically starts Avantra Server and Avantra UI via the web user interface.

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-25.0.n.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. Please 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`

note

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`