Updating Allegra

Updating Allegra#

This chapter describes how to update Allegra when installed using the ZIP package method on Windows systems. The update process is straightforward and involves replacing the allegra.jar file with a newer version.

Attention

CRITICAL: Always create backups before updating!

Before performing any update, you must backup:

  1. The database - Perform a full database backup

  2. ALLEGRA_HOME directory - Backup all files in your Allegra home directory

This ensures you can recover your data if any issues occur during the update process.

Understanding the Update Process#

What Gets Updated#

When updating Allegra, you are essentially replacing a single file:

  • bin\allegra.jar - The main Allegra application JAR file

What remains unchanged:

  • conf\application.properties - Your configuration settings

  • ALLEGRA_HOME directory - All your data (attachments, templates, indices)

  • Database - All your issue tracking data

  • allegra.ps1 and allegra.bat - Management scripts (updated separately)

How Updates Work#

Allegra updates follow a simple principle:

  1. The new allegra.jar contains updated application code

  2. When started, Allegra automatically detects the database schema version

  3. If needed, Allegra applies database schema migrations automatically

  4. Your configuration and data remain intact

This makes updates straightforward, but also emphasizes the importance of backups, as database schema changes are typically irreversible without restoring from backup.

Pre-Update Checklist#

Before starting the update process, complete this checklist:

Required Steps#

☐ 1. Backup the Database

Create a complete backup of your Allegra database. The method depends on your database system:

PostgreSQL:

pg_dump -U allegra_user -h localhost allegra > allegra_backup_YYYYMMDD.sql

MySQL/MariaDB:

mysqldump -u allegra_user -p allegra > allegra_backup_YYYYMMDD.sql

Microsoft SQL Server:

BACKUP DATABASE allegra
TO DISK = 'C:\Backups\allegra_backup_YYYYMMDD.bak'
WITH FORMAT;

Oracle:

Use Oracle Data Pump or RMAN to create a backup.

☐ 2. Backup ALLEGRA_HOME

Create a complete copy of your Allegra home directory:

robocopy "C:\allegra-data" "C:\backups\allegra-data_YYYYMMDD" /E /COPY:DAT

Or using Windows Explorer:

  1. Navigate to the parent folder of ALLEGRA_HOME

  2. Right-click on the ALLEGRA_HOME folder

  3. Select “Copy”

  4. Paste in your backup location

  5. Rename to include the date (e.g., allegra-data_20250104)

☐ 3. Verify Backup Integrity

Ensure your backups are complete:

  • Check database backup file size is reasonable (not empty)

  • Verify ALLEGRA_HOME backup contains all subdirectories

  • Test database backup restoration on a test system (recommended for production)

☐ 4. Note Current Version

Record your current Allegra version for reference:

allegra.bat version

Example output: Allegra version is 9.0.0b58

☐ 5. Check Available Disk Space

Ensure you have sufficient disk space:

  • At least 500 MB free in the Allegra installation directory

  • Sufficient space for database growth during migration

☐ 6. Review Release Notes

Visit the Allegra website and review the release notes for the version you’re updating to. Pay special attention to:

  • Breaking changes

  • New configuration requirements

  • Database migration notes

  • Known issues

Automatic Update Using allegra.bat#

The allegra.bat update command provides an automated update process that handles most steps for you.

Step 1: Check for Updates#

First, check if updates are available:

allegra.bat version

This displays your current version. Compare with the latest version available on the Allegra website: https://alltena.com

Step 2: Run the Update Command#

Execute the update command:

allegra.bat update

The update process will:

  1. Check script version - Warns if your management script is outdated

  2. Check current version - Reads version from your installed JAR

  3. Fetch latest version - Downloads version information from the server

  4. Compare versions - Determines if an update is available

  5. Prompt for backup confirmation - Reminds you to backup

  6. Download new version - Downloads the new allegra.jar

  7. Stop Allegra - Automatically stops the running instance

  8. Replace JAR file - Updates bin\allegra.jar

  9. Keep versioned backup - Saves the old JAR as bin\allegra-XXXbYY.jar

Example Update Session#

C:\allegra> allegra.bat update

Checking for Allegra updates...
Checking script version...
Current installed version: 9.0.0 build 58
Latest version available: 9.0.0 build 59

Before updating Allegra make sure you have a database or instance level backup,
do you want to continue?
(y/n): y

You will install Allegra version 9.0.0 build 59
Do you want to download this version? (y/n): y

Stopping Allegra before update...
Stopping Allegra application (found 1 process(es))...
Stopping process 12345...
Process 12345 stopped successfully.
Allegra stopped.

Downloading allegra-900b59.jar...
Successfully downloaded allegra-900b59.jar
Updated bin\allegra.jar

Application was updated successfully!
Now you can start it by running: allegra.bat start

Step 3: Start Updated Allegra#

After the update completes, start Allegra:

allegra.bat start

Step 4: Monitor Startup#

Watch the startup log for any errors:

type allegra-startup.log

Or monitor in real-time using PowerShell:

Get-Content allegra-startup.log -Wait

Step 5: Verify Update#

Once Allegra has started (wait 1-2 minutes), verify:

  1. Check version:

    allegra.bat version

  2. Access web interface:

    Open your browser and navigate to: http://localhost:8080

  3. Verify login:

    Log in with your credentials

  4. Check functionality:

    • Browse existing issues

    • Open a project

    • Check that attachments are accessible

    • Verify custom fields display correctly

  5. Review application logs:

    Check ALLEGRA_HOME\log\allegra.log for any errors or warnings

Manual Update Process#

If you prefer to update manually or if the automatic update fails, you can perform the update manually.

Step 1: Download New Version#

Download the latest allegra.jar from:

https://alltena.com/downloads/90x/

The file will be named something like: allegra-900b59.jar

Save it to a temporary location, such as: C:\temp\allegra-900b59.jar

Step 2: Stop Allegra#

Stop the running Allegra instance:

cd C:\allegra
allegra.bat stop

Verify it has stopped:

allegra.bat status

You should see: Allegra is not running

Step 3: Backup Current JAR#

Create a backup of your current JAR file:

copy bin\allegra.jar bin\allegra.jar.backup

Or rename it with version number:

move bin\allegra.jar bin\allegra-900b58.jar

Step 4: Replace JAR File#

Copy the new JAR file to the bin directory:

copy C:\temp\allegra-900b59.jar bin\allegra.jar

Verify the file was copied:

dir bin\allegra.jar

Step 5: Start Allegra#

Start Allegra with the new version:

allegra.bat start

Step 6: Monitor and Verify#

Follow the same monitoring and verification steps as described in the automatic update section above.

Updating the Management Script#

The allegra.ps1 management script may also receive updates with new features, bug fixes, and improvements.

Checking for Script Updates#

Check if a script update is available:

allegra.bat check-script-updates

Example output:

Checking for script updates...
Script update available!
Current checksum:  abc123def456...
Available checksum: def789ghi012...

There is an update for the script. Please download the latest version.

Updating the Script#

To update the script automatically:

allegra.bat update-script

The process will:

  1. Download the latest script checksum from the server

  2. Compare with your current script version

  3. Prompt for confirmation

  4. Download the new script

  5. Verify the downloaded script checksum

  6. Create a backup (allegra.ps1.backup)

  7. Replace the script with the new version

Example output:

Checking for script updates...
Script update available!
Current checksum:  abc123...
Available checksum: def456...

Do you want to update the script? (y/n): y

Downloading updated script...
Created backup: allegra.ps1.backup
Script updated successfully!
New checksum: def456...

Please run the script again to use the updated version.

Note

Script updates do not require stopping Allegra. The script is only used to manage Allegra, not to run it. You can update the script while Allegra is running.

Manual Script Update#

If automatic script update fails, you can update manually:

  1. Download the latest script from: https://alltena.com/downloads/90x/allegra.ps1

  2. Stop Allegra (if running)

  3. Backup current script: copy allegra.ps1 allegra.ps1.backup

  4. Replace with new script: copy C:\temp\allegra.ps1 allegra.ps1

  5. Start Allegra (if it was running)

Rolling Back an Update#

If you encounter issues after updating, you can roll back to the previous version.

Rolling Back the Application#

If you kept the old JAR file (automatic updates do this):

  1. Stop Allegra:

    allegra.bat stop

  2. Restore previous JAR:

    copy bin\allegra-900b58.jar bin\allegra.jar

    Or if you created a backup:

    copy bin\allegra.jar.backup bin\allegra.jar

  3. Start Allegra:

    allegra.bat start

Warning

Database Schema Considerations

If the new version applied database schema changes, rolling back the application JAR alone may not be sufficient. You may also need to restore the database backup.

Database migrations are typically forward-only and cannot be automatically reversed.

Restoring from Complete Backup#

If rolling back the JAR file is not sufficient:

  1. Stop Allegra:

    allegra.bat stop

  2. Restore database backup:

    PostgreSQL:

    dropdb -U postgres allegra
createdb -U postgres allegra
psql -U postgres allegra < allegra_backup_20250104.sql

    MySQL/MariaDB:

    mysql -u root -p -e "DROP DATABASE allegra; CREATE DATABASE allegra;"
mysql -u root -p allegra < allegra_backup_20250104.sql

    Microsoft SQL Server:

    RESTORE DATABASE allegra
FROM DISK = 'C:\Backups\allegra_backup_20250104.bak'
WITH REPLACE;

  3. Restore ALLEGRA_HOME:

    robocopy "C:\backups\allegra-data_20250104" "C:\allegra-data" /E /COPY:DAT

  4. Restore previous JAR:

    copy bin\allegra-900b58.jar bin\allegra.jar

  5. Start Allegra:

    allegra.bat start

  6. Verify restoration:

    • Check version: allegra.bat version

    • Access web interface

    • Verify your data is intact

Troubleshooting Update Issues#

Update Command Shows “Already Up to Date”#

If you believe an update should be available but the update command says you’re already up to date:

  1. Check version manually:

    allegra.bat version

  2. Visit the website:

    Check https://alltena.com for the latest version number

  3. Clear download cache:

    The version information is cached. Wait a few hours or manually download the latest JAR file.

Download Fails#

If the automatic download fails:

  1. Check internet connectivity

  2. Verify firewall settings

  3. Try manual update (see Manual Update Process above)

  4. Check download URL is accessible: https://alltena.com/downloads/90x/

Allegra Won’t Start After Update#

If Allegra fails to start after updating:

  1. Check startup log:

    type allegra-startup.log

  2. Check application log:

    Review ALLEGRA_HOME\log\allegra.log

  3. Common issues:

    • Database connection errors - Verify database is running

    • Schema migration errors - Check logs for SQL errors

    • Insufficient memory - Increase memory allocation

    • Port conflicts - Ensure port 8080 is available

  4. If errors persist, roll back to the previous version

Database Migration Fails#

If database schema migration fails during startup:

  1. Check database logs for errors

  2. Verify database user permissions - Must have DDL rights

  3. Check database disk space - Ensure sufficient space

  4. Review error in allegra.log for specific SQL errors

  5. If migration fails completely:

    • Stop Allegra

    • Restore database backup

    • Restore previous JAR file

    • Contact Allegra support

Performance Degradation After Update#

If Allegra runs slower after updating:

  1. Clear browser cache - Old cached JavaScript may conflict

  2. Check memory allocation:

    allegra.bat show-config

  3. Review system resources - CPU, memory, disk I/O

  4. Check database performance - Index maintenance may be needed

  5. Review release notes - Check for known performance issues

Best Practices#

Regular Update Schedule#

  • Check for updates monthly - Run allegra.bat update monthly

  • Subscribe to announcements - Stay informed about security updates

  • Plan major updates - Schedule major version updates during low-usage periods

Testing Updates#

  • Use staging environment - Test updates on staging before production

  • Document custom configurations - Note any customizations that need testing

  • Verify integrations - Test external integrations after updating

Backup Strategy#

  • Automated backups - Set up automated database backups

  • Backup retention - Keep at least 7 days of backups

  • Test restorations - Regularly verify backups can be restored

  • Off-site backups - Store backups in a separate location

Documentation#

  • Maintain update log - Document when updates are performed

  • Record issues - Note any problems encountered

  • Version tracking - Keep track of which versions were used when

Version Compatibility#

  • Check compatibility - Verify plugin compatibility before updating

  • Review deprecations - Check for deprecated features you use

  • API changes - Review API changes if using REST API

  • Browser support - Verify supported browser versions

Security Updates#

Critical Security Updates#

Some updates address critical security vulnerabilities. These updates should be applied as soon as possible.

Security updates are announced on:

  • Allegra website: https://alltena.com

  • Email notifications (if subscribed)

  • Security mailing list

Priority Update Process#

For critical security updates:

  1. Review security advisory - Understand the vulnerability

  2. Assess your exposure - Determine if your instance is affected

  3. Create emergency backup - Quick backup before update

  4. Apply update immediately - Don’t wait for regular update schedule

  5. Verify patch applied - Check version and test vulnerability is fixed

  6. Notify users - Inform users that security update was applied

Summary Checklist#

Before Every Update#

☐ Backup database completely ☐ Backup ALLEGRA_HOME directory ☐ Note current version ☐ Review release notes ☐ Check available disk space

Performing Update#

☐ Run allegra.bat update (automatic) ☐ Or manually replace bin\allegra.jar ☐ Verify new JAR file is in place ☐ Start Allegra

After Update#

☐ Monitor startup logs ☐ Verify version number ☐ Test web interface login ☐ Check basic functionality ☐ Review application logs ☐ Notify users system is back online

If Problems Occur#

☐ Review error logs ☐ Check troubleshooting section ☐ Attempt rollback if necessary ☐ Restore from backup if needed ☐ Contact support if unresolved

Getting Help#

If you encounter issues during the update process:

  1. Review documentation - Check this guide and troubleshooting sections

  2. Check application logs - allegra-startup.log and ALLEGRA_HOME\log\

  3. Visit support forum - Community support at https://alltena.com/forum

  4. Contact support - Email support@alltena.com with:

    • Current Allegra version

    • Target update version

    • Error messages from logs

    • Steps that led to the issue

    • Your configuration (sanitize passwords)

  5. Emergency support - For critical production issues, contact your support contract

Contents