With Docker Installer¶

This section provides a step-by-step description of the installation process for Allegra in a Docker container with a PostgreSQL database.

This section describes

How to obtain the Allegra Docker package
How to install and run Allegra in a Docker container

Allegra Docker Package¶

Step 1: Download Allegra Docker Package¶

Download the Allegra Docker Package from the Allegra download page and save it in an empty directory.

mkdir $HOME/adocker
cd $HOME/adocker
export WORKDIR="$HOME/adocker"
wget https://www.trackplus.com/files/downloads/latest-dist/core/allegra-latest-docker.tar -O allegra-docker.tar

Step 2: Unpack Allegra Docker Package¶

Unpack the file:

tar -xvf allegra-docker.tar
ls -al

You should among others now see:

a command file allegra-quickstart.sh
a Docker file allegra-$VERSION.dockerfile
a Docker file allegra-base.dockerfile
a Docker file allegra-base-tex.dockerfile

Preparation¶

Hardware Requirements¶

Make sure that the requirements regarding the runtime environment are met.

Check Docker Installation¶

Make sure Docker is installed on your server and the Docker daemon is running.

docker ps --all

Installation with Docker Composer¶

With the help of Docker Composer you can manage the federation of database and Servlet container more easily than with a script. Before you start the system for the first time, you should

create a working directory
configure the working directory
adjust the HTTP port where Allegra will be accessible
optionally set the available memory

You make the corresponding settings in the hidden file .env. It looks for example like this:

CONTEXT=demo
ALLEGRA_HOME=/tmp/allegra
HTTP_PORT=8082
JAVA_OPTS=-Djava.awt.headless=true -Xmx1024m -Xms512m

1. Create working directory¶

Create a directory that will contain configuration data, indexes and attachments for your Allegra instance. There should be between 1 and 10 GBytes of disk space available, depending on the available, depending on the level of usage and number of users. In the following we will call this ALLEGRA_HOME.

mkdir -p $HOME/allegra
export ALLEGRA_HOME=$HOME/allegra

2. Configure working directory¶

Open the file .env and adjust the variable ALLEGRA_HOME to your environment. Make sure that the working directory ALLEGRA_HOME exists and is writable.

3. Configure HTTP port¶

In the .env file set the variable HTTP_PORT to the desired value.

4. Configure JAVA_OPTS¶

In the file .env set the variable JAVA_OPTS to the desired value. Here you can especially configure the available main memory (minimum: 512 MB).

Start system¶

Save the configuration file and start the system with

docker compose up -d

The associated control file is called docker-compose.yml and looks like this:

version: "3.9"
services:
    db:
        image: postgres:13-bullseye
        restart: always
        container_name: allegra-${CONTEXT}-db
        volumes:
            - ${ALLEGRA_HOME}/dbdata:/var/lib/postgresql/data
        environment:
            - POSTGRES_DB=allegra-${CONTEXT}
            - POSTGRES_USER=allegra
            - POSTGRES_PASSWORD=tissi189
        ports:
            - "8001:5432"
        healthcheck:
            test: ["CMD-SHELL", "pg_isready -U allegra -d allegra-${CONTEXT}"]
            interval: 10s
            timeout: 5s
            retries: 2
    allegra:
        image: allegrapm/core:7.2
        restart: always
        container_name: allegra-${CONTEXT}
        volumes:
            - ${ALLEGRA_HOME}:/home/allegra
        environment:
            JAVA_OPTS: ${JAVA_OPTS}
            CONTEXT: ${CONTEXT}
            DB_URL: jdbc:postgresql://db/allegra-${CONTEXT}
            DB_USER: allegra
            DB_PASSWD: tissi189
        ports:
            - "${HTTP_PORT}:8080"
            - "8089:8009"
        depends_on:
            db:
                condition: service_healthy

The Allegra image uses several environment variables to create a database connection and a file location for storing attachments and configuration files.

Hint

The environment variables described below refer to the Allegra image and are not directly related to the entries in the .env'' file for Docker Composer. A reference is only made, if at all, via the file ``docker-compose.yml.

`CONTEXT`¶

The CONTEXT environment variable determines the URL, under which the Allegra instance will be visible. The URL will look like http://<yourmachine>:8080/$CONTEXT, assuming you have mapped port 8080 of the container to 8080 outside of your container. The default value is allegra.

`DB_URL`¶

This defines the JDBC driver URL under which Allegra can find the database. This database has to exist before you start Allegra. The user defined by DB_USER and password DB_PASSWD should have been granted all permissions to this database.

Here are some DB_URL examples:

PostgreSQL: jdbc:postgresql://yourdbserver/allegra
MySQL: jdbc:mysql://localhost:3306/allegra?useSSL=false&useUnicode=true&characterEncoding=UTF-8&zeroDateTimeBehavior=convertToNull&serverTimezone=UTC
Oracle: jdbc:oracle:thin:@80.96.67.62:1521:orcl
Microsoft SQLServer: jdbc:jtds:sqlserver://localhost/allegra
Firebird: jdbc:firebirdsql://localhost/home/allegra/dbase/ALLEGRA.GDB?charSet=UTF-8
DB2: jdbc:db2:ALLEGRA

`DB_ADAPTER`¶

To connect to a database Allegra needs to know its type. The following types are supported by this image:

postgresql
mysql
mssql
oracle (with additional library)
firebird
db2app (with additional library)

Hint

Oracle and DB2 databases need additional JDBC driver libraries that do not come with this image. See Adding JDBC Drivers for more information.

The default database system being used is PostgreSQL.

`DB_DRIVER`¶

With this variable you define the JDBC driver class to be used. It depends on the type of database you want to use (DB_ADAPTER).

The default is org.postgresql.Driver for a PostgreSQL database.

Other examples are:

MySQL: org.gjt.mm.mysql.Driver
Oracle: oracle.jdbc.driver.OracleDriver
Microsoft SQLServer: net.sourceforge.jtds.jdbc.Driver
Firebird: org.firebirdsql.jdbc.FBDriver
DB2: com.ibm.db2.jdbc.app.DB2Driver

`DB_USER`¶

DB_USER defines the user under which Allegra accesses the database. The default value is allegra.

`DB_PASSWD`¶

DB_PASSWD defines the password for the user under which Allegra accesses the database.

The default value is Tissi189

`JAVA_OPTS`¶

The JAVA_OPTS are handed over to the Allegra/Tomcat virtual machine. Here you can set the memory available to your Allegra instance. Example and default:

-Djava.awt.headless=true -Xmx2048m -Xms512m -XX:MaxRAM=2500m -Duser.timezone=Europe/Berlin

Adding JDBC Drivers¶

We recommend to add additional JDBC drivers by creating a new Docker image based on the Allegra image. The libraries should be placed in the /usr/local/tomcat/lib directory.

Security¶

If you want to run the Allegra server productively, you should put it behind an nginx, Apache or IIS proxy server. This way you can ensure that only SSL-secured connections are used and you do not expose the Tomcat to the Internet.

Instructions on how to do this can be found here, for example: