Updating Allegra

Updating Allegra#

This chapter describes how to update Allegra when installed using the ZIP package method on Ubuntu and other Linux distributions. 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.sh script - Management script (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:

PostgreSQL:

pg_dump -U allegra_user -h localhost allegra > allegra_backup_$(date +%Y%m%d).sql

# Or with compression
pg_dump -U allegra_user allegra | gzip > allegra_backup_$(date +%Y%m%d).sql.gz

MySQL/MariaDB:

mysqldump -u allegra_user -p allegra > allegra_backup_$(date +%Y%m%d).sql

# Or with compression
mysqldump -u allegra_user -p allegra | gzip > allegra_backup_$(date +%Y%m%d).sql.gz

☐ 2. Backup ALLEGRA_HOME

Create a complete copy of your Allegra home directory:

tar -czf allegra-home_$(date +%Y%m%d).tar.gz /opt/allegra-data

Or using rsync:

rsync -av /opt/allegra-data/ /backup/allegra-data_$(date +%Y%m%d)/

☐ 3. Verify Backup Integrity

Ensure your backups are complete:

# Check backup file size
ls -lh allegra_backup_*.sql.gz
ls -lh allegra-home_*.tar.gz

# Test database backup can be read
gunzip -c allegra_backup_*.sql.gz | head -n 20

☐ 4. Note Current Version

Record your current Allegra version:

cd /opt/allegra
./allegra.sh version

Example output: Allegra version is 900b58

☐ 5. Check Available Disk Space

Ensure sufficient disk space:

df -h /opt/allegra
df -h /opt/allegra-data

You need at least 500 MB free for the new JAR file.

☐ 6. Review Release Notes

Check the Allegra website for release notes and review:

  • Breaking changes

  • New configuration requirements

  • Database migration notes

  • Known issues

Automatic Update Using allegra.sh#

The ./allegra.sh update command provides an automated update process.

Step 1: Check for Updates#

First, check your current version:

./allegra.sh version

Compare with the latest version on https://alltena.com

Step 2: Run the Update Command#

Execute the update command:

cd /opt/allegra
./allegra.sh update

The update process will:

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

  2. Check current version - Reads version from installed JAR

  3. Fetch latest version - Downloads version information from server

  4. Compare versions - Determines if 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 running instance

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

Example Update Session#

$ ./allegra.sh 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 application with PID 12345...
Stopped.

Downloading allegra-900b59.jar...
Successfully downloaded allegra-900b59.jar
Removing old bin/allegra.jar...
Updated bin/allegra.jar

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

Step 3: Start Updated Allegra#

For standalone installation:

./allegra.sh start

For systemd service installation:

sudo systemctl start allegra

Step 4: Monitor Startup#

Watch the startup log:

tail -f allegra-startup.log

Or for systemd service:

sudo journalctl -u allegra -f

Step 5: Verify Update#

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

  1. Check version:

    ./allegra.sh version

  2. Check service status (if using systemd):

    sudo systemctl status allegra

  3. Access web interface:

    Open browser: http://localhost:8080

  4. Verify functionality:

    • Log in with your credentials

    • Browse existing issues

    • Check attachments are accessible

    • Verify custom fields display correctly

  5. Review application logs:

    tail -f $ALLEGRA_HOME/log/allegra.log

Manual Update Process#

If automatic update fails, perform manual update:

Step 1: Download New Version#

cd /tmp
wget https://alltena.com/downloads/90x/allegra-900b59.jar

Step 2: Stop Allegra#

Standalone:

cd /opt/allegra
./allegra.sh stop

Systemd service:

sudo systemctl stop allegra

Verify it has stopped:

./allegra.sh status

Step 3: Backup Current JAR#

cp bin/allegra.jar bin/allegra.jar.backup

Or with version number:

mv bin/allegra.jar bin/allegra-900b58.jar

Step 4: Replace JAR File#

cp /tmp/allegra-900b59.jar bin/allegra.jar
chmod 644 bin/allegra.jar

Step 5: Start Allegra#

Standalone:

./allegra.sh start

Systemd service:

sudo systemctl start allegra

Step 6: Monitor and Verify#

Follow the same verification steps as in the automatic update section.

Updating the Management Script#

Check for Script Updates#

./allegra.sh check-script-updates

Update the Script#

./allegra.sh update-script

The script will:

  1. Download latest version

  2. Verify checksum

  3. Create backup (allegra.sh.backup)

  4. Replace script

Note

Script updates can be done while Allegra is running.

Rolling Back an Update#

Rolling Back the Application#

If you kept the old JAR:

# Stop Allegra
./allegra.sh stop
# or: sudo systemctl stop allegra

# Restore previous JAR
cp bin/allegra-900b58.jar bin/allegra.jar

# Start Allegra
./allegra.sh start
# or: sudo systemctl start allegra

Restoring from Complete Backup#

If rolling back JAR is insufficient:

1. Stop Allegra:

./allegra.sh stop
# or: sudo systemctl stop allegra

2. Restore database:

PostgreSQL:

sudo -u postgres psql -c "DROP DATABASE allegra;"
sudo -u postgres psql -c "CREATE DATABASE allegra OWNER allegra_user;"
gunzip -c allegra_backup_20250104.sql.gz | sudo -u postgres psql allegra

MySQL:

mysql -u root -p -e "DROP DATABASE allegra; CREATE DATABASE allegra;"
gunzip -c allegra_backup_20250104.sql.gz | mysql -u root -p allegra

3. Restore ALLEGRA_HOME:

rm -rf /opt/allegra-data/*
tar -xzf allegra-home_20250104.tar.gz -C /

4. Restore previous JAR:

cp bin/allegra-900b58.jar bin/allegra.jar

5. Start Allegra:

./allegra.sh start
# or: sudo systemctl start allegra

Troubleshooting Update Issues#

Update Command Shows “Already Up to Date”#

Check version manually and compare with website:

./allegra.sh version
# Compare with https://alltena.com

Download Fails#

  1. Check internet connectivity

  2. Try manual download

  3. Verify URL is accessible:

    curl -I https://alltena.com/downloads/90x/allegra-900b59.jar

Allegra Won’t Start After Update#

  1. Check startup log:

    cat allegra-startup.log

  2. Check application log:

    tail -100 $ALLEGRA_HOME/log/allegra.log

  3. Common issues:

    • Database connection errors

    • Schema migration errors

    • Insufficient memory

    • Port conflicts

  4. If errors persist, roll back

Database Migration Fails#

If schema migration fails:

  1. Check database logs

  2. Verify database user has DDL permissions

  3. Check available disk space

  4. Review error in allegra.log

  5. If migration fails completely:

    • Stop Allegra

    • Restore database backup

    • Restore previous JAR

    • Contact support

Performance Issues After Update#

  1. Clear browser cache

  2. Check memory allocation:

    ./allegra.sh show-config | grep memory

  3. Review system resources:

    top
free -h
df -h

  4. Check database performance

  5. Review release notes for known issues

Best Practices#

Regular Update Schedule#

  • Check for updates monthly

  • Subscribe to Allegra announcements

  • Plan major version updates during low-usage periods

Testing Updates#

  • Use staging environment if available

  • Document custom configurations

  • Verify integrations after updating

Backup Strategy#

  • Automated backups - Set up cron jobs for daily backups:

    # /etc/cron.daily/allegra-backup
#!/bin/bash
BACKUP_DIR="/backup/allegra"
DATE=$(date +%Y%m%d)

# Database backup
pg_dump -U allegra_user allegra | gzip > "$BACKUP_DIR/db_$DATE.sql.gz"

# ALLEGRA_HOME backup
tar -czf "$BACKUP_DIR/home_$DATE.tar.gz" /opt/allegra-data

# Keep only last 7 days
find "$BACKUP_DIR" -type f -mtime +7 -delete

  • Backup retention - Keep at least 7 days of backups

  • Test restorations - Periodically verify backups can be restored

  • Off-site backups - Store backups on separate server or cloud storage

Security Updates#

Critical security updates should be applied immediately:

  1. Review security advisory

  2. Assess your exposure

  3. Create emergency backup

  4. Apply update

  5. Verify patch applied

  6. Notify users

Summary Checklist#

Before Every Update#

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

Performing Update#

☐ Stop Allegra (or let script do it) ☐ Run ./allegra.sh update ☐ Or manually replace bin/allegra.jar ☐ Start Allegra

After Update#

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

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 logs - allegra-startup.log and ALLEGRA_HOME/log/

  3. Check system logs - sudo journalctl -u allegra (if using systemd)

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

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

    • Current Allegra version

    • Target update version

    • Error messages from logs

    • Steps that led to the issue

    • System information (uname -a, database version)

Contents