Updating Allegra

Updating Allegra#

This chapter describes how to update Allegra on Ubuntu/Debian systems installed using the ZIP package method.

Attention

Before updating, ensure you have a full backup of your database and your $ALLEGRA_HOME directory (which contains attachments, templates, and configuration files — defined during installation and typically separate from the installation directory).

Preparation#

Before you begin, ensure the following:

  • Allegra is stopped (see “Summary” below)

  • Database and $ALLEGRA_HOME backups are complete

  • Java 21 JRE/JDK is installed and available in your system PATH

  • You have sudo privileges (if running as a systemd service)

  • There is sufficient free disk space in your <INSTALLATION_DIRECTORY>

Summary#

In your <INSTALLATION_DIRECTORY> (e.g., /opt/allegra or /home/ubuntu/allegra), run the following commands in sequence.

# Stop Allegra (standalone)
./allegra.sh stop

# If installed as a systemd service:
# sudo systemctl stop allegra

# Update Allegra
./allegra.sh update

# Start Allegra (standalone)
./allegra.sh start

# If installed as a systemd service:
# sudo systemctl start allegra

# Verify version
./allegra.sh version

Note

The <INSTALLATION_DIRECTORY> contains Allegra’s program files and scripts. During setup, Allegra also created a separate $ALLEGRA_HOME directory where Allegra stores all attachments and configuration files. Always back up the database and $ALLEGRA_HOME before performing an update.

Updating the Management Script#

Updating the management script (allegra.sh) is rarely required. If a newer version is needed, Allegra will usually prompt you automatically during the normal update process.

You can also check and update it manually if needed:

  1. Check for script updates

    ./allegra.sh check-script-updates

  2. Update the script

    ./allegra.sh update-script

    This command downloads and installs the latest version of the script, verifying checksums and creating a backup (allegra.sh.backup) before replacement.

Note

Script updates do not require stopping Allegra. The script is used for administrative tasks, not for running the server process.

Troubleshooting#

Common issues and their resolutions:

  • Update download fails – Check internet connection or firewall; try manual download

  • Allegra does not start – Review allegra-startup.log and $ALLEGRA_HOME/log/catalina.out

  • Database connection errors – Ensure the DB server is running and reachable; verify credentials with ./allegra.sh show-config

  • Out of memory – Increase memory allocation with ./allegra.sh setup-memory

  • Service not starting (systemd) – Check sudo systemctl status allegra and sudo journalctl -u allegra

Next Steps#

After completing the update, perform the following checks to ensure the installation is healthy:

  1. Verify application startup Check that Allegra starts correctly and is accessible in your browser.

  2. Review application logs Inspect $ALLEGRA_HOME/log/catalina.out for any errors or warnings.

  3. Confirm database connection Verify Allegra can connect to your configured database.

  4. Inform users Notify users once the update is complete and tested.

Best Practices#

  • Maintain a regular update cadence (e.g., monthly checks)

  • Review release notes before updating

  • Always back up database and $ALLEGRA_HOME

  • Test in staging if available

  • Keep at least 7 days of backups and periodically test restores