How to Upgrade Your Koha Server to a New AMI Version

Overview

When KohaSupport publishes a new version of Koha to the AWS Marketplace, a new AMI (Amazon Machine Image) is released for each tier. Upgrading your deployment to that AMI brings you the latest Koha release, security patches, and any KohaSupport infrastructure improvements baked into the image.

The upgrade experience is fundamentally different depending on your tier:

If you are on Standard or Enterprise, continue through this guide. The process is straightforward: update one CloudFormation parameter, wait a few minutes, and your library is running the new version with all data intact.

If you are on the Free tier, skip to Free Tier Upgrade Path below.

⚠ STOP — Do Not Proceed Without a Verified Backup

Upgrading replaces your EC2 instance. This cannot be undone.

Before you touch anything in CloudFormation, you must confirm that a recent, verified backup of your Koha database exists in S3. If the upgrade goes wrong — a botched database migration, a misconfigured volume mount, anything — your S3 backup is the only way to get your library data back.

“I think we have a backup” is not good enough. Verify it. The steps to do so are in Step 1 below.

If you do not have a recent backup, run one now before continuing. Do not skip this step. Instance replacement cannot be undone.

→ How to Restore Koha from S3 Backup — bookmark this before you start.

Step 1 — Verify Your Backups Are Current and Restorable

This is the most important step in the entire process. Do not treat it as a formality.

Find your backup bucket

Your backup bucket is named <stack-name>-koha-backup-<account-id>. To find it:

1. Open the AWS S3 console.
2. Search for your stack name — the bucket will appear in the results.
3. Click into the bucket and open the library/databases/ prefix.

You should see .sql.gz files with timestamps in the filename. If the library/databases/ prefix does not exist or is empty, your backups are not running — do not proceed with the upgrade.

Check from the command line

aws s3 ls s3://<bucket-name>/library/databases/ --profile kohasupport-marketplace

The output should look like this:

2026-04-29 02:15:03   48234521 koha_library_20260429_021500.sql.gz
2026-04-28 02:15:01   47998234 koha_library_20260428_021500.sql.gz

What to check:

• The most recent file should be within the last 24 hours for production systems.
• File sizes should be consistent with previous days (a sudden drop to near-zero indicates a failed backup).
• There should be multiple files — not just one.

Check the backup log on the server

sudo tail -50 /var/log/koha/s3-backup.log

Look for SUCCESS or COMPLETED near the end. If you see errors, investigate and resolve them before upgrading.

If no recent backup exists — run one now

SSH or SSM into your Koha server and trigger a manual backup:

sudo koha-s3-backup --bucket <bucket-name> --yes

Wait for it to complete, then re-verify the S3 listing above before continuing. Do not skip to the next step while the backup is still running.

Step 2 — Find the New AMI ID

AMI IDs are region-specific. Make sure you select the AMI for the same AWS region where your stack is deployed.

1. Go to the AWS Marketplace and search for KohaSupport Koha.
2. Open the listing for your tier (Standard or Enterprise — match what you currently have).
3. Click Continue to Subscribe (if not already subscribed, accept the terms).
4. Click Continue to Configuration.
5. Set the Region to match your current deployment region (e.g. us-east-1).
6. Under Fulfillment option, select Amazon Machine Image (AMI).
7. From the Software version dropdown, select the latest version.
8. Click Continue to Launch.
9. On the Launch page, the AMI ID is shown in the header area — it looks like ami-0abc1234def56789a. Copy it.

Tip: You can also find the current AMI ID in the KohaSupport changelog or release announcements, which include the AMI ID for each region alongside the version number.

Do not launch the AMI from this page — you only need the ID.

Step 3 — Note Your Current Stack Details (Safety Check)

Before making any changes, record the key identifiers for your current deployment. If you need to roll back, these values are essential.

1. Open the AWS CloudFormation console.
2. Click your Koha stack.
3. Click the Outputs tab.
4. Record the following values:

1. Open the EC2 Volumes console.
2. Search for the DataVolumeId you just noted.
3. Confirm the volume is in In-use state and the Attachment information shows your current instance.

If the data volume does not appear, or is not In-use, stop here and contact KohaSupport before proceeding. The volume must exist and be attached before you update the stack.

Step 4 — Update the CloudFormation Stack

This step replaces the EC2 instance with a new one running the new AMI. The process takes 5–10 minutes.

1. In the CloudFormation console, select your Koha stack.
2. Click Update.
3. Select Use current template and click Next.
4. On the Parameters page, find the parameter named ImageId.
5. Replace the existing AMI ID with the new AMI ID you copied in Step 2.
6. Leave all other parameters unchanged. Do not modify EBSVolumeSize, domain settings, instance type, or any other parameter. Changing multiple things at once makes rollback harder.
7. Click Next through the Options page (no changes needed).
8. On the Review page, confirm the only change is the ImageId parameter.
9. Tick the acknowledgement checkbox if prompted (for IAM-related changes).
10. Click Update stack.

The stack status changes to UPDATE_IN_PROGRESS. Your Koha server will be unavailable for approximately 3–5 minutes while the instance is replaced and the new one boots.

Do not cancel the update once it starts. Cancelling mid-update may leave the stack in an inconsistent state. Wait for it to reach either UPDATE_COMPLETE or UPDATE_ROLLBACK_COMPLETE.

What Happens During the Update

Understanding the sequence helps you know what to expect — and what to check if something goes wrong.

1. CloudFormation terminates the existing EC2 instance. Your Koha OPAC and staff interface go offline.
2. The data EBS volume is NOT deleted. Because it is declared with DeletionPolicy: Retain in the CloudFormation template, the volume persists independently of the instance lifecycle.
3. A new EC2 instance is launched with the new AMI.
4. The Elastic IP is reassociated with the new instance. Your DNS and SSL certificates continue to work without changes.
5. The user-data script runs on first boot. It looks up the data volume ID from the SSM Parameter Store at /koha/<stack-name>/data-volume-id, attaches the volume to the instance, mounts it, and starts Koha. This is fully automatic — no manual intervention required.
6. Koha starts against your existing data. Your database, configuration, SSL certificates, and any customisations stored on the data volume are available immediately. Koha runs any required database schema migrations automatically on startup.
7. The stack reaches UPDATE_COMPLETE.

Total downtime is typically 3–5 minutes, depending on instance type and Koha startup time.

Step 5 — Verify the Upgrade

Once the CloudFormation stack shows UPDATE_COMPLETE, work through the following checks before declaring the upgrade done.

Confirm the stack completed successfully

• Stack status: UPDATE_COMPLETE (green)
• Events tab: scroll to the bottom and confirm no errors

Confirm the Elastic IP is still assigned

Open the Outputs tab of your stack and verify the ElasticIP value is the same as before. Then open the EC2 console and confirm the Elastic IP is associated with the new instance.

Confirm the data volume is attached

1. EC2 console → Instances → your new Koha instance → Storage tab.
2. You should see two volumes: the root volume and the data volume.
3. The data volume ID should match the DataVolumeId you recorded in Step 3.

If only one volume appears, see Troubleshooting below.

Confirm Koha is accessible

Open your Koha OPAC URL (or http://<elastic-ip> if you haven’t set up a custom domain). The Koha OPAC should load. Log in to the staff interface and confirm your library data — items, patrons, circulation records — is present.

Verify the new Koha version

1. In the Koha staff interface, go to Administration → About Koha.
2. The version number displayed should match the new release you upgraded to.
3. Check the Database tab in About Koha — it should report that the database schema is up to date.

Review Koha release notes

Check the Koha Community manual and release notes for the version you just installed. Some releases include new system preferences or deprecated features that benefit from manual review. Koha applies database schema updates automatically on startup, but reviewing the release notes helps you catch changes that affect your workflows.

Free Tier Upgrade Path

The Free tier Koha instance stores all data — including the Koha database — on the root EBS volume. That volume is configured with DeleteOnTermination: true, which means it is destroyed when the instance is terminated. A CloudFormation stack update that replaces the instance also destroys the root volume and all data on it.

Upgrading a Free tier deployment is not a simple parameter change. You have three options:

Option 1 — Upgrade in place via apt (not recommended for production)

SSH into your Free tier instance and upgrade Koha using the package manager:

sudo apt-get update
sudo apt-get upgrade koha-common

This keeps your data in place because the instance is not replaced. However, it is not recommended for production because:

• Package upgrades on a running production system carry risk.
• The KohaSupport AMI includes Koha plus a specific configuration layer — a package-only upgrade may miss AMI-level improvements.
• You will not be on the tested, supported AMI version.

Use this only for non-critical libraries where downtime is acceptable and you understand the risks.

Option 2 — Export, launch new instance, restore (recommended)

This is the cleanest upgrade path for Free tier:

1. Back up your Koha database from the current instance:

   sudo koha-dump library
   

   Copy the dump file off the instance (via SCP, or upload to S3 manually).

2. Launch a fresh Koha Free tier instance from the Marketplace listing, selecting the new version.

3. Once the new instance is running, restore your database dump:

   sudo koha-restore /path/to/library.tar.gz
   

4. Reconfigure any customisations (system preferences, patron categories, notice templates) that were not captured in the dump.

Option 3 — Upgrade to Standard tier (best long-term path)

If your library is growing and you are on Free tier, the AMI upgrade is a natural point to move to Standard tier. Standard tier gives you a persistent EBS data volume, an Elastic IP, S3 automated backups, and the straightforward CloudFormation upgrade path described above. Future upgrades will be a 5-minute parameter change rather than a manual migration.

Launch a Standard tier stack from the Marketplace, restore your Free tier database dump, and decommission the Free tier instance.

Rollback Procedure

If the upgrade completes but something is wrong — Koha is unreachable, data appears missing, or you discover a compatibility issue — you can roll back to the previous AMI version.

Roll back the instance

1. CloudFormation console → your stack → Update.
2. Select Use current template.
3. On the Parameters page, set ImageId back to the previous AMI ID.
4. Complete the update.

The data volume reattaches to the old AMI exactly as it did with the new one. Your library data is not version-specific — both old and new AMIs read the same volume.

Roll back the database

If the new Koha version ran database schema migrations and you need to fully undo them, a schema rollback via apt is not practical. In this scenario:

1. Confirm you are back on the old AMI instance (complete the rollback above first).
2. Stop Koha: sudo koha-stop-zebra library && sudo service apache2 stop
3. Restore the database from your pre-upgrade S3 backup: see How to Restore Koha from S3 Backup.

This is why Step 1 is non-negotiable — your pre-upgrade S3 backup is the only reliable rollback path for the database layer.

Troubleshooting

Stack status: UPDATE_ROLLBACK_COMPLETE

The update failed and CloudFormation restored the previous instance. Your Koha server should be back online on the old version. Open the Events tab of the stack and scroll to find the first CREATE_FAILED or UPDATE_FAILED event — the status reason will describe the error. Common causes:

• The new AMI ID is invalid for the selected region — verify the AMI ID against Step 2.
• The AMI is from a different account or is not shared with your account — confirm you are using the Marketplace AMI, not a private one.
• An IAM permission was missing — check the Events tab status reason for the specific permission.

Koha is unreachable after the update

The new instance is likely still booting. The user-data script runs on first boot and takes 2–4 minutes. Wait 5 minutes and try again before investigating further.

If it is still unreachable after 5 minutes:

1. EC2 console → your new instance → check that Instance state is Running and Status checks show 2/2 checks passed.
2. Check the security group — make sure ports 80, 443, 8080, and 8090 are open from your source IP.
3. Check the Elastic IP association in the EC2 console.

Data appears missing after the upgrade

Koha loaded but your library data is not there — the web installer appears, or you see an empty catalogue.

First, confirm the data volume is actually attached:

1. EC2 console → your new instance → Storage tab.
2. Count the volumes. You should see two: a root volume (typically 20–30 GB) and a data volume (the size you configured when the stack was created).
3. If only one volume is listed, the data volume did not attach. Check the user-data log on the instance:

sudo cat /var/log/koha-userdata.log

Look for errors around the volume attachment step. The log will show which SSM parameter was queried and whether the attach-volume call succeeded.

Data volume mounted but Koha is pointing at local storage

SSH into the instance and verify the data volume is mounted at the expected path:

df -h | grep kohadata

Expected output:

/dev/xvdf       200G   45G  155G  23% /mnt/kohadata

If nothing appears, the volume attached but did not mount. Check /var/log/koha-userdata.log for the mount step and run:

sudo mount /mnt/kohadata

If the mount fails, check /etc/fstab for the data volume entry and verify the volume is visible in lsblk.

Koha web installer appears instead of my library

This means Koha started but could not find its database. Most likely the data volume is not mounted. Run:

df -h | grep kohadata
sudo systemctl status koha-common
sudo journalctl -u koha-common --no-pager -n 50

If the volume is not mounted, follow the steps above to mount it manually, then restart Koha:

sudo service apache2 restart
sudo koha-start-zebra library

If the issue persists after mounting the volume, the MySQL data directory may not be on the data volume. Contact KohaSupport with the output of the above commands.