How to Upgrade Your Koha Server to a New AMI Version

What is an AMI upgrade?

KohaSupport periodically releases a new AMI — a pre-built server image containing an updated version of Koha, the latest OS security patches, and any infrastructure improvements made to the server configuration. Upgrading replaces your server with a fresh instance built from this image. Your library data is stored separately and carries over automatically.

Which tier are you on?

Not sure which tier you are on? Log into the AWS CloudFormation console, click your Koha stack, and open the Parameters tab. Your tier is shown in the KohaSupport Tier parameter.

Did you launch your Koha server directly from EC2 — not via CloudFormation? Steps 3–5 below use CloudFormation and Auto Scaling Groups and do not apply to you. Skip to Direct EC2 Upgrade Path instead.

• Standard or Enterprise (CloudFormation): Follow Steps 1–6 below.
• Free tier (CloudFormation): Skip to Free Tier Upgrade Path.
• Direct EC2 launch (no CloudFormation): Skip to Direct EC2 Upgrade Path.

⚠ Stop — Check Your Backup First

Upgrading replaces your server. This cannot be undone.

Before changing anything in AWS, confirm you have a recent backup of your Koha database. If something goes wrong during the upgrade, your backup is the only way to recover your library data.

→ How to Restore Koha from S3 Backup — open this in a separate tab before you start.

Step 1 — Check Your Backup Before Anything Else

Standard and Enterprise tier

Your server runs automated daily backups to an S3 bucket (Amazon’s cloud storage). You need to confirm those backups are working and up to date.

Check your backup bucket in the AWS Console:

1. Open the AWS S3 console.
2. Find the bucket named something like your-stack-name-koha-backup-123456789.
3. Click into it and open the library/databases/ folder.
4. You should see backup files with today’s or yesterday’s date in the filename.

If you don’t see any recent files, your automated backups may not be running. Do not upgrade until you have a confirmed backup.

Run a manual backup now (strongly recommended before any upgrade):

Connect to your server using EC2 Instance Connect:

1. Open the EC2 console.
2. Click Instances and select your Koha server.
3. Click Connect → EC2 Instance Connect → Connect.

In the terminal that opens, run:

sudo koha-s3-backup

Wait for the command to finish (usually 2–5 minutes). Then go back to the S3 console and confirm a new backup file appeared.

Check the backup log:

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

Look for SUCCESS or Upload complete near the end. If you see error messages, contact KohaSupport before proceeding.

Step 2 — Find the New AMI ID

Each new Koha release gets a new AMI ID — a unique code that identifies that version of the server image. You need this code to update your server.

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, then Continue to Configuration.
4. Set the Region to match your deployment region (e.g. us-east-1 for US East Virginia).
5. Under Fulfillment option, select Amazon Machine Image (AMI).
6. From the Software version dropdown, select the latest version.
7. Click Continue to Launch.
8. The AMI ID is shown at the top — it looks like ami-0abc1234def56789a. Copy it.

You do not need to launch anything from this page. You only need the AMI ID code.

Step 3 — Record Your Current Settings

Before making any changes, write down these values. If anything goes wrong, you will need them to recover.

1. Open the AWS CloudFormation console.
2. Click your Koha stack.
3. Click the Outputs tab.
4. Write down:
   • ElasticIP — your server’s fixed public IP address (your library website’s address)
   • DataVolumeId — the ID of the separate drive holding your library data (e.g. vol-0abc1234)
   • StackName — the name of your Koha setup
5. Confirm the data drive is working:
   • Open the EC2 Volumes console.
   • Search for your DataVolumeId.
   • It should show as In-use. If it shows anything else, stop and contact KohaSupport before continuing.

Step 4 — Update the AMI in CloudFormation

This step tells AWS to use the new server image the next time a new server starts. Your current Koha server keeps running while this happens — there is no downtime yet.

AWS gives you two ways to apply the update. Change set is recommended — it lets you review exactly what will change before anything happens.

Option A: Change Set (Recommended)

A change set shows you a preview of what CloudFormation will modify before you commit. This is the safest approach.

1. In the CloudFormation console, click your Koha stack.
2. Click Stack actions → Create change set for current stack.
3. Select Use current template and click Next.
4. On the Parameters page, find the setting named ImageId.
5. Replace the existing value with the new AMI ID you copied in Step 2.
6. Do not change any other settings. Click Next.
7. On the Options page, leave everything as-is. Click Next.
8. Give the change set a name (e.g. upgrade-ami-2026-05-29). Click Create change set.
9. Wait a few seconds for the change set to be created. It will show a list of proposed changes.
10. Review the changes — you should see only the ImageId parameter change listed. If anything else is flagged for replacement or deletion, stop and contact KohaSupport before proceeding.
11. Click Execute change set → Execute.

Wait until the stack status changes to UPDATE_COMPLETE (usually under a minute). Your Koha server is still running on the old version at this point — that’s expected.

Option B: Direct Update

If you prefer a faster path and are confident in what you are changing, you can update the stack directly without a preview.

1. In the CloudFormation console, click your Koha stack.
2. Click Update.
3. Select Use current template and click Next.
4. On the Parameters page, find the setting named ImageId.
5. Replace the existing value with the new AMI ID you copied in Step 2.
6. Do not change any other settings.
7. Click Next on the Options page (nothing to change there).
8. Review the summary — confirm only the ImageId parameter changed.
9. Tick any acknowledgement checkbox if shown.
10. Click Update stack.

Wait until the status changes to UPDATE_COMPLETE (usually under a minute). Your Koha server is still running on the old version at this point — that’s expected.

Step 5 — Replace the Server

Now you trigger the actual upgrade by replacing the old server with a new one. This causes a brief outage — typically 5–8 minutes.

Your library data is stored on a separate drive. That drive is not deleted when the old server is replaced — it is automatically attached to the new server when it starts.

Via the AWS Console (recommended):

1. Open EC2 → Auto Scaling Groups.
2. Find the group named your-stack-name-asg.
3. Click the Instance Management tab.
4. Select your current instance (the one listed there).
5. Click Actions → Terminate → select Do not decrease desired capacity → confirm.

Your Koha OPAC and staff interface go offline. A new server starts automatically within a few minutes.

Via the command line (optional — only if you are comfortable with the AWS CLI):

STACK=your-stack-name
REGION=us-east-1

ASG=$(aws cloudformation describe-stack-resources   --stack-name "$STACK"   --query "StackResources[?ResourceType=='AWS::AutoScaling::AutoScalingGroup'].PhysicalResourceId"   --output text --region "$REGION")

INSTANCE=$(aws autoscaling describe-auto-scaling-groups   --auto-scaling-group-names "$ASG"   --query "AutoScalingGroups[0].Instances[0].InstanceId"   --output text --region "$REGION")

echo "Replacing instance: $INSTANCE"
aws autoscaling terminate-instance-in-auto-scaling-group \
  --instance-id "$INSTANCE" \
  --no-should-decrement-desired-capacity \
  --region "$REGION"

Replace your-stack-name and us-east-1 with your actual values.

What Happens During the Server Replacement

1. The old server shuts down. Your library website goes offline.
2. AWS automatically starts a fresh server using the new AMI.
3. The new server finds and attaches your data drive (your library data).
4. Koha starts up, applies any required database updates automatically, and reconnects your fixed IP address.
5. Your library website comes back online — same address, same data, newer Koha version.

Total downtime: 5–8 minutes from when you terminate the old server.

Step 6 — Verify the Upgrade

Once the new server is running, check everything before declaring the upgrade complete.

Check the CloudFormation status:

• Status should be UPDATE_COMPLETE
• Click Events and confirm no red errors

Check your IP address:

• Outputs tab → ElasticIP should be the same address as before the upgrade

Check your data drive is attached:

• EC2 console → Instances → new instance → Storage tab
• You should see two volumes: a small root drive and your larger data drive
• The data drive ID should match what you wrote down in Step 3

Check Koha is working:

• Open your OPAC URL — your library catalogue should load
• Log into the staff interface and confirm your items, patrons, and records are there

Check the Koha version:

• In the staff interface: Administration → About Koha
• The version shown should match the new release

Free Tier Upgrade Path

The Free tier stores all library data — including the database — on the main server drive. When the server is replaced, that drive is deleted. You must copy your data off the server before upgrading.

If you are on Free tier and your stack was created before May 2026, see the Free Tier Data Volume Migration guide first. Newer Free tier stacks use a separate data drive, like Standard tier.

Option A — Back up and restore (recommended)

1. Connect to your server via EC2 Instance Connect (EC2 console → your instance → Connect).

2. Create a backup:

sudo koha-dump library

This creates two files in /var/spool/koha/library/ — a .sql.gz database file and a .tar.gz configuration file.

3. Copy the backup to S3 (replace your-bucket-name with your actual bucket):

aws s3 cp /var/spool/koha/library/koha-library-*.sql.gz \
  s3://your-bucket-name/koha-upgrade-backup/

If you do not have an S3 bucket, create one in the S3 console first, or contact KohaSupport for help.

4. Launch a new Free tier instance from the Marketplace listing, choosing the new version.

5. Connect to the new server via EC2 Instance Connect once it is running.

6. Download and restore your backup:

aws s3 cp s3://your-bucket-name/koha-upgrade-backup/koha-library-backup.sql.gz \
  /home/ubuntu/koha-library-backup.sql.gz

sudo koha-restore /home/ubuntu/koha-library-backup.sql.gz

7. Verify your data is there, then terminate the old server.

Option B — Upgrade software in place (not recommended for production)

You can upgrade Koha without replacing the server, keeping your data intact:

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

This is not recommended for production because it is not the same tested configuration as a fresh AMI, and you may miss infrastructure improvements included in the new release.

Option C — Move to Standard tier

If you are growing and want easier future upgrades, this is a natural time to move. Standard tier gives you:

• A separate data drive (survives server replacements permanently)
• Automated daily S3 backups
• Future upgrades in 5 minutes instead of a manual migration process

Contact KohaSupport if you would like help making the move.

Rollback — If Something Goes Wrong

If Koha is not working after the upgrade and you need to go back to the previous version:

1. Find your old AMI ID (check your notes from Step 3, or the CloudFormation change history).
2. Repeat Steps 4 and 5 using the old AMI ID.
3. Your data drive reattaches to the old version exactly as it did to the new one.

If you also need to restore your database to its state before the upgrade:

1. Complete the rollback above first (get back to the old AMI).
2. Follow the Koha restore guide.

This is why checking your backup in Step 1 is essential — your pre-upgrade backup is the only reliable way to undo database changes.

Troubleshooting

The site is still down after 10 minutes

The new server is likely still starting up. Wait another 5 minutes. If still down:

1. EC2 console → check the new instance shows Running and 2/2 checks passed
2. Confirm the Elastic IP is associated with the new instance (EC2 → Elastic IPs)
3. Connect via EC2 Instance Connect and check the startup log:

   sudo tail -30 /var/log/koha-userdata.log
   

   This log shows exactly what happened when the server started.

My library data is gone — I see the Koha web installer

This means Koha started but cannot find the database. The data drive may not have attached correctly.

1. EC2 console → your new instance → Storage tab — do you see two drives?
2. If you only see one, connect via EC2 Instance Connect and check:

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

3. Contact KohaSupport with that log and we will help you recover your data.

CloudFormation shows UPDATE_ROLLBACK_COMPLETE

The update failed and CloudFormation restored the previous state automatically. Your Koha server should be back online on the old version.

Click the Events tab and find the first red event — the message will explain the error. Common causes:

• The AMI ID is for the wrong AWS region
• The AMI is not from a Marketplace listing you are subscribed to

Contact KohaSupport if you are unsure how to resolve the error.

Direct EC2 Upgrade Path

This section is for users who launched their Koha server directly from the EC2 Launch Wizard or the Marketplace “Launch from EC2 Console” button — without a CloudFormation stack. You have no ASG or CFN Outputs tab. The upgrade process is manual but straightforward.

Before you start: Complete Step 1 (backup) and Step 2 (new AMI ID) first — those steps apply regardless of how you deployed.

EC2 Step 1 — Record your current settings

Open the EC2 console and note down:

• Instance ID of your current Koha server (e.g. i-0abc1234)
• Elastic IP allocation ID — EC2 → Elastic IPs → find the IP address for your server → copy the Allocation ID (e.g. eipalloc-0abc1234)
• Data volume ID — EC2 → Instances → your instance → Storage tab → find the volume attached as /dev/sdb or /dev/xvdb (e.g. vol-0abc1234). This is your library data volume — it must not be the root volume (/dev/sda1).
• Subnet, Security Group, and IAM instance profile from the instance details (you will need these when launching the new instance)

EC2 Step 2 — Stop the old instance

Do not terminate — stop it. This detaches the data volume cleanly without deleting it.

1. EC2 → Instances → select your Koha server
2. Instance state → Stop instance → confirm
3. Wait for the status to show Stopped
4. EC2 → Volumes → find your data volume ID → confirm it shows Available (not In-use)

EC2 Step 3 — Launch a new instance from the new AMI

1. Go to the AWS Marketplace and find your KohaSupport listing.
2. Click Continue to Subscribe → Continue to Configuration.
3. Set the region to match your current deployment. Select the new software version.
4. Click Continue to Launch → Launch through EC2.
5. In the EC2 launch wizard:
   • Instance type: match your previous instance type
   • Key pair: use the same key pair, or select an existing one
   • Network: select the same VPC and subnet as before
   • Security group: select the same security group as before
   • IAM instance profile: select the same profile as before (the one with SSM and S3 permissions)
   • Storage: the root volume (/dev/sda1) is pre-configured — do not add the data volume here
6. Launch the instance and wait for it to reach Running and 2/2 checks passed.

EC2 Step 4 — Attach the data volume to the new instance

1. EC2 → Volumes → select your data volume (the one you noted in EC2 Step 1)
2. Actions → Attach volume
3. Select your new instance from the Instance dropdown
4. Set the device name to /dev/sdb (or /dev/xvdb — match what it was on the old instance)
5. Click Attach volume
6. Wait for the volume to show In-use

EC2 Step 5 — Re-associate the Elastic IP

1. EC2 → Elastic IPs → find your Elastic IP
2. Actions → Associate Elastic IP address
3. Set Resource type to Instance
4. Select your new instance
5. Tick Allow this Elastic IP address to be reassociated → Associate

Your library’s public address now points to the new server.

EC2 Step 6 — Verify the upgrade

Wait 3–5 minutes for Koha to start up on the new instance, then check:

• Open your OPAC URL — your library catalogue should load
• Log into the staff interface — confirm items, patrons, and records are intact
• Check the Koha version: Administration → About Koha
• Check startup log via EC2 Instance Connect:

  sudo tail -50 /var/log/koha-userdata.log
  

  Look for Koha started successfully near the end.

• Check the data volume is mounted:

  df -h | grep kohadata
  

  If this returns nothing, the volume may not have been picked up. Run sudo systemctl restart koha-mount-data and check again.

Once you have confirmed everything is working, terminate the old stopped instance.

EC2 Rollback

If the new instance does not come up correctly:

1. Detach the data volume from the new instance (EC2 → Volumes → Detach)
2. Re-attach it to the old stopped instance at /dev/sdb
3. Start the old instance
4. Re-associate the Elastic IP back to the old instance
5. Contact KohaSupport for help diagnosing the issue

Need Help?

Upgrades are straightforward in most cases, but if your data appears missing or Koha shows errors, contact KohaSupport before doing anything else — especially before terminating the old server. We can help you recover remotely.