Docker Installation (Unix)

Docker Installation (Unix)#

This guide describes how to install and run Allegra on Unix-based systems using Docker Compose and the official pre-packaged Docker bundle.

This method provides a ready-to-run Allegra Docker image (including Java 21), together with a separate PostgreSQL database container.

Attention

This guide is not intended to make your server secure for public access over the Internet. Additional individual security measures are required for that purpose.

Preparation#

Before installation, ensure the following:

  • Unix-based system (Docker’s OS support)

  • Docker Engine and Docker Compose installed and running (Get Docker)

  • Sufficient disk space (at least 20 GB)

  • Available network port (default 8080 or as configured)

  • User account with permission to run Docker commands (sudo or docker group)

Note

All Allegra data — configuration, attachments, logs, and the database — is stored in the persistent host folder you set as ALLEGRA_HOME_DIR, which is mounted to /home/allegra inside the container.

Installation Steps#

Follow these steps to install and start Allegra using Docker Compose.

  1. Create the Allegra home directory

    Create a persistent directory on your host system that will store Allegra data. This directory is referred to throughout this guide as ALLEGRA_HOME.

    sudo mkdir -p /home/ubuntu/allegra-home
sudo chmod 750 /home/ubuntu/allegra-home
sudo chown -R 999:999 /home/ubuntu/allegra-home

    Note

    ls may show the group as systemd-journal instead of 999 (on many Ubuntu hosts GID 999 maps to that group). This is cosmetic — Allegra uses the numeric ID, so keep ownership at 999:999.

  2. Download the Allegra Docker package

    Download the latest prepackaged Allegra Docker bundle from the Allegra downloads page.

    wget https://alltena.com/downloads/allegra/latest-dist/allegra-docker.zip

  3. Unpack the archive

    unzip allegra-docker.zip
cd allegra-docker

    The extracted archive contains the following files: - docker-compose.yml - env (environment variable template) - application.properties (Spring Boot configuration, mounted into the container) - README.md

  4. Configure environment variables

    Open the file env in a text editor and adjust the settings to match your environment. In particular, set ALLEGRA_HOME_DIR to the absolute path of your persistent Allegra home directory (ALLEGRA_HOME) created in step 1, and set DB_PASSWORD to a strong database password.

    Example configuration:

    CONTEXT=demo
TZ=Europe/Berlin
ALLEGRA_HOME_DIR=/home/ubuntu/allegra-home  # Set your ALLEGRA_HOME path here
HTTP_PORT=8080
JAVA_OPTS=-Djava.awt.headless=true -Xmx2048m -Xms1024m
DB_USER=allegra
DB_PASSWORD=tissi189

    Note

    Use the ALLEGRA_HOME_DIR directory for Allegra only. Never point it at a user’s home directory or another shared folder: on hosts with SELinux, Docker relabels this directory and everything in it.

  5. Rename the file to `.env`

    Docker Compose automatically reads environment variables from a file named .env.

    mv env .env

  6. Start Allegra

    Launch Allegra in the background with Docker Compose:

    sudo docker compose up -d

    This will: - Pull the Allegra image specified in the shipped docker-compose.yml - Mount the host directory /home/ubuntu/allegra-home as persistent storage - Map port HTTP_PORT on your host to the same port inside the container - Start Allegra automatically (restart: always)

  7. Access Allegra

    After a short startup time, open a browser and go to:

    http://<host>:${HTTP_PORT}/${CONTEXT}

    where <host> is localhost if you are browsing on the server itself, or the server’s IP address or hostname when accessing it from another machine, and ${CONTEXT} is the context you set in your env file (default demo).

    With the default settings, Allegra is available at http://localhost:8080/demo (e.g. http://192.168.1.10:8080/demo from another machine).

    Default login credentials:

    • Username: admin

    • Password: tissi

    Warning

    For security reasons, you must change the default administrator password immediately after the first login. Use a strong password and store it securely.

Operation#

To manage the container:

docker compose ps        # Check status
docker compose logs -f   # View live logs
docker compose stop      # Stop Allegra
docker compose start     # Start again
docker compose down      # Stop and remove container

Updating Allegra#

To upgrade Allegra to a newer version, edit your docker-compose.yml file and update the image tag, for example:

image: alltena/allegra:<version> #You can find the current version in our release notes

Then pull the new image and restart the container:

docker compose pull
docker compose up -d

Note

If your docker-compose.yml comes from an older Allegra Docker package, switch to the docker-compose.yml of the current package (see step 2) and transfer your settings. Older files lack the :z suffix on the volume lines, which hosts with SELinux need.

Note

Upgrading from Allegra 8.x: Files created by the old image may belong to a different user, and Allegra then stops at startup with an AccessDeniedException. Set the ownership of everything in ALLEGRA_HOME except the database folder to 999:999:

cd /home/ubuntu/allegra-home
sudo chown 999:999 .
sudo find . -mindepth 1 -maxdepth 1 ! -name dbdata -exec chown -R 999:999 {} +

Replace dbdata with the name of your database folder if it differs (e.g. mysql).

Troubleshooting#

Mounted Files Cannot Be Read (SELinux)#

On hosts with SELinux (RHEL and derivatives such as Rocky or Alma Linux, Fedora, Fedora CoreOS), the containers can only access the mounted files if every volume line in docker-compose.yml ends with :z. The docker-compose.yml of the current Allegra Docker package already contains it. Without it, one of these symptoms appears:

  • The db container does not start. docker compose logs db shows Permission denied.

  • The allegra container stops with ERROR: data directory '/home/allegra' is not writable (see docker compose logs allegra), although the directory is owned by 999:999.

  • Allegra stops with Allegra home /home/ubuntu/allegra does not exist and can't be created. This path is the built-in default: Allegra could not read your application.properties.

To check whether Docker uses SELinux, run:

docker info --format '{{.SecurityOptions}}'

If the output contains name=selinux, show the SELinux labels of the mounted files. Run the command in the folder that contains docker-compose.yml:

ls -dZ <ALLEGRA_HOME_DIR> application.properties

Files that the containers can access have the type container_file_t. Any other type, such as user_home_t, means that :z is missing. Add :z to the volume lines as in the docker-compose.yml of the current Allegra Docker package and recreate the containers:

docker compose down
docker compose up -d

docker compose restart is not enough, because it does not apply changes made to docker-compose.yml.

Uninstall#

To remove Allegra and its data:

Warning

This will permanently delete all Allegra data stored in your ALLEGRA_HOME.

docker compose down
docker rmi alltena/allegra:<version>
docker rmi postgres:18
sudo rm -rf /home/ubuntu/allegra-home

After successful installation, secure your instance by changing the admin password and configuring HTTPS via a reverse proxy (see Nginx Proxy Example or Apache Proxy Example).