Ubuntu/Debian Installation

Ubuntu/Debian Installation#

This chapter describes a streamlined installation method for Allegra on Ubuntu 22/24 LTS (or Debian 12) using a pre-packaged ZIP file from our resources page. For updating Allegra to a newer version, see Updating Allegra.

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 you begin the installation, ensure you have the following:

  • Linux system (Ubuntu 22/24 LTS or Debian 12 recommended)

  • Sufficient disk space (at least 20 GB, see hardware requirements)

  • Java 21 JRE/JDK installed and available in your system PATH (you can install via APT)

  • A running Allegra-supported database (we recommend PostgreSQL 18, see database setup instructions)

  • Available network port (default 8080, or your chosen port) for the Allegra server

  • Permissions to run shell scripts; sudo privileges if installing as a systemd service

  • Core utilities typically pre-installed (curl/wget, unzip, sha256sum)

Installation#

Follow these steps to install Allegra on Ubuntu 24 LTS using the ZIP package and management script.

  1. Download the ZIP package from the Allegra resources page. Save it as /tmp/allegra.zip (or another location).

    cd /tmp
# Using wget (replace ZIP_URL with the direct ZIP link from the resources page)
wget -O allegra.zip "<ZIP_URL>"

# Or using curl
curl -L -o allegra.zip "<ZIP_URL>"

  2. Extract the ZIP file to your installation directory (e.g., /home/ubuntu/allegra). This will be your installation directory, referenced as <INSTALLATION_DIRECTORY>.

    mkdir -p /home/ubuntu/allegra
cd /home/ubuntu/allegra
unzip /tmp/allegra.zip

    After extraction, you should see:

    • allegra.sh — Management script

    • bin/ — Contains allegra.jar

    • conf/ — Contains application.properties

    • allegra.service — systemd service template

  3. Make the management script executable.

    chmod +x allegra.sh

  4. Verify Java installation.

    ./allegra.sh check-java

    If Java is not found or not version 21+, install Java 21 and ensure it’s in your PATH.

  5. Run the setup wizard.

    ./allegra.sh install

    Follow the prompts to configure: * Home directory (recommended: /home/ubuntu/allegra/allegra-home) * Database connection * Server port and context path * Memory settings

    (These map to entries in conf/application.properties.)

  6. (Optional) Install Allegra as a systemd service for automatic startup after reboot.

    sudo ./allegra.sh install-service

    You’ll be shown the resolved service file before installation. Confirm to proceed.

  7. Start Allegra.

    Attention

    If you installed as a systemd service, start Allegra with sudo systemctl start allegra instead.

    ./allegra.sh start

  8. Access Allegra in your browser at http://localhost:8080 (or your configured port or context-path) and log in with:

    • Username: admin

    • Password: tissi

Note

The <INSTALLATION_DIRECTORY> contains Allegra’s program files and scripts. During setup, Allegra also creates a separate <ALLEGRA_HOME> directory where Allegra stores all attachments and configuration files.

Ensure that Java 21 JRE/JDK and a supported database server are installed before running the installer. Change the default admin password immediately after your first login.

Operation#

Manual Startup and Shutdown#

Attention

If you installed as a systemd service, use sudo systemctl <command> allegra.

To start, stop, or check the status of Allegra manually, open a terminal in the installation directory and run:

cd <INSTALLATION_DIRECTORY>
./allegra.sh start
./allegra.sh stop
./allegra.sh status

Automatic Startup (Service)#

When installed as a service, Allegra is enabled to start automatically at boot. You can control it via systemctl:

sudo systemctl start allegra
sudo systemctl stop allegra
sudo systemctl restart allegra
sudo systemctl status allegra
sudo journalctl -u allegra -f   # Live logs

Uninstall systemd service#

To remove the Allegra systemd service, run:

sudo ./allegra.sh uninstall-service

Updating#

To update Allegra to a newer version, see Updating Allegra.

Next Steps#

After successful installation, you should:

  1. Secure access

    • Log in and change the default admin password immediately.

    • Review firewall settings and restrict access to the Allegra port.

    • For Internet-facing deployments, use a reverse proxy (Apache, Nginx) and enable HTTPS/SSL.

      See:

  2. Configure backups

    • Configure regular backups for both the database and the ALLEGRA_HOME directory.

  3. Customize Allegra

    • Configure projects, users, and workflows.

    • See the Allegra User Guide.

  4. Maintain your installation

    • Keep Allegra up to date using ./allegra.sh update.

    • Use strong database passwords and limit database network access.

  5. Optional

Troubleshooting#

Application Won’t Start#

  1. Check Java installation:

    ./allegra.sh check-java

  2. Check if the default port (8080) is already in use:

    sudo ss -tulpn | grep :8080
# or:
sudo netstat -tulpn | grep :8080

  3. Review the startup log:

    cat allegra-startup.log

  4. Check the application log:

    tail -f $ALLEGRA_HOME/log/catalina.out

  5. Verify database connectivity:

    Ensure your database server is running and reachable from the Allegra host.

    # PostgreSQL
pg_isready -h localhost -p 5432

# MySQL
mysqladmin ping -h localhost

Application Won’t Stop#

If ./allegra.sh stop doesn’t work:

ps aux | grep allegra.jar
kill <PID>         # or: kill -9 <PID> if needed
rm -f allegra.pid  # remove stale PID file

Script Permission Denied#

If you get “Permission denied” when running the script:

chmod +x allegra.sh
./allegra.sh help

Out of Memory Errors#

If you encounter an OutOfMemoryError in the logs:

./allegra.sh stop
./allegra.sh setup-memory   # Enter a higher memory value when prompted
./allegra.sh start

Database Connection Errors#

If Allegra cannot connect to the database:

  1. Ensure the database server is running.

    # PostgreSQL
sudo systemctl status postgresql

# MySQL
sudo systemctl status mysql

  2. Check firewall and network settings:

    sudo ufw status

  3. Verify database credentials and configuration:

    ./allegra.sh show-config

  4. Test the connection using a database client tool.

Systemd Service Issues#

If the systemd service won’t start:

sudo systemctl status allegra
sudo journalctl -u allegra -n 50
sudo systemctl cat allegra

# Check file ownership/permissions for the service user:
ls -la /home/ubuntu/allegra/allegra.sh
ls -la /home/ubuntu/allegra/allegra.pid

Additional Commands#

The following useful commands are available in the <INSTALLATION_DIRECTORY>:

./allegra.sh help                 # Display help information
./allegra.sh install              # Full interactive setup
./allegra.sh setup-home           # Configure Allegra home directory
./allegra.sh setup-db             # Configure database connection
./allegra.sh setup-server         # Configure server settings (port, context)
./allegra.sh setup-memory         # Configure memory settings
./allegra.sh show-config          # Display current configuration
./allegra.sh check-java           # Verify Java installation
./allegra.sh version              # Display current version
./allegra.sh update               # Update Allegra to latest version
./allegra.sh update-script        # Update allegra.sh script to latest version
./allegra.sh check-script-updates # Check update script version
sudo ./allegra.sh install-service # Install as systemd service (requires sudo)
sudo ./allegra.sh uninstall-service # Remove systemd service

Key Properties#

The following important configuration properties are stored in <INSTALLATION_DIRECTORY>/conf/application.properties:

# Allegra home directory
allegra.home=/home/ubuntu/allegra/allegra-home

# Database configuration
allegra.db.adapter=postgresql
allegra.db.driver=org.postgresql.Driver
allegra.db.url=jdbc:postgresql://localhost:5432/allegra
allegra.db.username=allegra
allegra.db.password=secret

# Server configuration
server.port=8080
server.servlet.context-path=/

# Memory configuration (in MB)
allegra.server.memory=2048