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

  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

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