With Docker Installer

With Docker Installer#

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

Preparation#

Hardware Requirements#

Ensure that the prerequisites regarding the runtime environment are met.

Check Docker Installation#

Ensure that Docker is installed on your server and the Docker daemon is running.

/home/ubuntu$ docker ps --all

Hint

You might need to log in as a superuser using sudo su or use the sudo command for the subsequent steps described here.

Overview of the Installation Process#

The installation process includes the following steps:

  1. Create a working directory

  2. Download the Allegra Docker installation package

  3. Unzip your installation package

  4. Configure your installation via the configuration file .env in the working directory

  5. Start the installation with the Docker command compose.

Allegra Docker Installation Process#

Step 1: Create working directory#

Create a directory that contains the configuration data, indices, and attachments for your Allegra instance. It should have between 1 and 10 GB of storage available, depending on usage and number of users. Ensure that the working directory is writable.

In the following, we will call this directory $ALLEGRA_HOME.

Step 2: Download Allegra Docker Composer package#

Download the Allegra Docker Composer package from the Allegra Download Page and save it in an empty directory.

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

Step 3: Unzip the Allegra Docker package#

Unzip the file:

tar -xvf allegra-docker.tar
ls -al

You should see, among other things:

  • a file env

  • a Docker composition file docker-compose.yml

Step 4: Allegra Docker Composer Configuration#

Configure your installation via the hidden configuration file .env in the working directory. For this, move the file env to .env:

mv env .env

The configuration file might look something like this:

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

Step 4.1 Configure Allegra working directory#

Open the configuration file .env and adjust the variable ALLEGRA_HOME to fit your environment. Ensure that the working directory ALLEGRA_HOME exists and is writable (see Step 1). The final configuration file might look like this:

CONTEXT=allegra
ALLEGRA_HOME=/home/ubuntu/allegra
HTTP_PORT=80
JAVA_OPTS=-Djava.awt.headless=true -Xmx1024m -Xms512m

Step 4.2. Configure HTTP Port#

In the file .env, set the variable HTTP_PORT to the desired value. This is the port under which your Allegra instance will be accessible.

Step 4.3. Configure JAVA_OPTS#

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

Step 5: Start the system#

Save the configuration file .env and start the system with

docker compose up -d

Background#

The installation is controlled via the Docker compose file called docker-compose.yml. This file looks like this (the version numbers may change over time):

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

Contents