Persistent data volume not automatically mounted after AMI upgrade or instance replacement

Overview

KohaSupport Standard tier deployments use a persistent EBS data volume labeled kohadata. This volume survives instance replacements and AMI upgrades. It holds:

• MySQL/MariaDB database (Koha catalog and configuration)
• Koha configuration files (/etc/koha/sites/)
• Site data (/var/lib/koha/)
• SSL certificates (/etc/letsencrypt/)

When a CloudFormation stack update causes an Auto Scaling Group instance refresh (for example, during an AMI version upgrade), a new EC2 instance is launched from the new AMI. Due to a bug in the bootstrap script, the new instance does not automatically detect the existing kohadata EBS volume, mount it, or migrate data from it into the running system. The instance starts with a fresh default state.

The library OPAC and staff interface may be inaccessible or may show an empty or default Koha installation until the volume is manually mounted and data is migrated. Your library data is not lost — it remains safely on the EBS volume.

Affected Versions

• Standard tier (x86_64 and arm64) AMI builds released before 2026-05-29

Free tier stacks do not use a persistent data volume and are not affected.

Symptoms

After an AMI upgrade (stack update with instance refresh):

• The OPAC or staff interface shows a default or empty Koha installation
• The library catalog and patron data appear missing
• The kohadata EBS volume shows as available in the EC2 console but is unattached or attached but not mounted
• /var/log/koha-bootstrap.log contains no mention of kohadata

How to Check if You Are Affected

Connect to your instance via Session Manager (SSM) or SSH and run:

# Check if the kohadata volume exists and is detected
blkid -L kohadata

# Check if it is currently mounted
mount | grep datavolume

If blkid -L kohadata returns a device path (e.g. /dev/xvdf), the volume is attached to the instance but not mounted. If mount | grep datavolume returns empty output, the data volume is not in use by the running system.

You can also check the bootstrap log for evidence of volume handling:

grep -i kohadata /var/log/koha-bootstrap.log

If this returns no output, the bootstrap script did not detect the volume during boot.

Remediation

Important: Your data is NOT lost. The kohadata EBS volume has DeletionPolicy: Retain in the CloudFormation template and will not be deleted during stack updates. Do not panic — and do not terminate your instance or delete the volume.

Option 1: Wait for Patched AMI (Recommended)

A patched AMI is being prepared that includes automatic kohadata volume detection and data migration logic in the bootstrap script. On first boot after the upgrade, the script will detect the volume, mount it, and migrate data into the running instance automatically.

When the patched AMI is available, upgrade your stack using the standard procedure:

See How to Upgrade Koha to a New AMI Version.

Option 2: Contact Support for Immediate Remediation

Contact KohaSupport support immediately. We can remotely connect to your instance via Session Manager, mount the volume, and migrate your data back into the running instance on your behalf.

Contact: [email protected] or use the contact form.

Do NOT terminate your instance or delete the EBS volume while waiting for support.

Option 3: Self-Service Manual Remediation (Advanced)

If you are comfortable with Linux administration, you can mount the volume and restore data manually:

1. Identify the device:

   DEVICE=$(blkid -L kohadata)
   echo "Device: $DEVICE"
   

2. Mount the volume:

   mkdir -p /mnt/datavolume
   mount "$DEVICE" /mnt/datavolume
   

3. Migrate data back:

   # Stop services first
   sudo systemctl stop koha-common mariadb
   
   # Rsync data from the volume
   sudo rsync -av /mnt/datavolume/mysql/        /var/lib/mysql/
   sudo rsync -av /mnt/datavolume/koha-lib/     /var/lib/koha/
   sudo rsync -av /mnt/datavolume/koha-sites/   /etc/koha/sites/
   sudo rsync -av /mnt/datavolume/letsencrypt/  /etc/letsencrypt/
   
   # Fix ownership
   sudo chown -R mysql:mysql /var/lib/mysql
   
   # Restart services
   sudo systemctl start mariadb koha-common
   

4. Verify the OPAC and staff interface are accessible before unmounting.

If you are unsure at any step, stop and contact support rather than risking data loss.

Timeline