Deploy Koha via AMI: Direct EC2 Launch from AWS Marketplace

KohaSupport Koha on AWS is available in two ways from the AWS Marketplace listing: via a CloudFormation template (recommended for most libraries), and as a standalone AMI that you launch directly from the EC2 Launch Wizard or the Marketplace “Launch from EC2 Console” button.

This guide covers the standalone AMI path — useful when you need custom networking, want to attach an existing EBS volume, or simply prefer to configure the instance yourself.

Most libraries should use CloudFormation instead. The CloudFormation templates handle security groups, Elastic IPs, and EBS volume attachment automatically. See Deploy Koha on AWS with CloudFormation if you are unsure which path to take.

When to use the direct AMI launch

Use this guide when you:

• want to place the instance inside an existing VPC or subnet
• need to attach an existing EBS data volume from a previous deployment
• require a specific IAM instance profile, Placement Group, or Dedicated Host
• are rebuilding after an instance failure and want to skip CloudFormation
• are an advanced user who prefers the EC2 Launch Wizard over CloudFormation

Prerequisites

Before you begin:

• An AWS account with EC2 launch permissions
• An IAM user or role with ec2:RunInstances, ec2:CreateKeyPair (or an existing key pair), and ec2:CreateSecurityGroup (or an existing security group)
• A connection method — choose one:
  • SSM Session Manager (recommended) — no open ports or key pair required; connect via the AWS Console or aws ssm start-session CLI; requires an IAM instance profile with AmazonSSMManagedInstanceCore attached (configured in Step 3) and the SSM agent running (pre-installed on the KohaSupport AMIs)
  • EC2 Instance Connect — browser-based terminal, no key pair required; works on instances in a public subnet with port 22 open
  • SSH key pair — a .pem key pair downloaded from the EC2 console (classic, works everywhere)
• Basic familiarity with the AWS Console

Step 1 — Find the Koha AMI on the Marketplace

1. Sign in to the AWS Marketplace and search for KohaSupport Koha.
2. Open the KohaSupport Koha listing for your desired tier (Free, Standard, or Enterprise).
3. Click Continue to Subscribe if you have not already subscribed.
4. After accepting terms, click Continue to Configuration.
5. Select your AWS Region and Fulfillment option — choose Amazon Machine Image (AMI) (not CloudFormation Template).
6. Choose the latest Software version from the dropdown.
7. Click Continue to Launch.
8. On the Launch page, change the launch method to Launch from EC2 Console and click the button.

You will be redirected to the EC2 Launch Wizard with the AMI pre-selected.

Step 2 — Configure the instance in the EC2 Launch Wizard

Name and tags

Give the instance a meaningful name, for example koha-standard-prod.

Instance type

ARM64 AMIs: If the listing shows an ARM64 AMI, select a Graviton instance type (e.g. t4g.medium, m7g.large). ARM64 AMIs will not run on x86 instance types and vice versa.

Key pair

Select an existing key pair or create a new one. Download the .pem file and keep it safe — you will need it for SSH access.

If you plan to use EC2 Instance Connect or SSM Session Manager instead of SSH, you can proceed without a key pair, but you must configure the instance profile in the Advanced Details section (see Step 3).

Network settings

Security group — required inbound rules:

You can restrict port 22 to your office IP range for better security. Port 8080 is required for initial staff interface access before SSL is configured.

Storage (volumes)

The AMI includes a root volume (typically 30 GB) with the OS and Koha application.

Recommended: add a separate data volume for Standard and Enterprise tiers.

Library data (MySQL databases, uploaded files) lives under /mnt/koha-data on Standard/Enterprise AMIs. Placing this on a separate EBS volume means you can:

• replace or upgrade the AMI without losing library data
• snapshot the data volume independently

To add a data volume:

1. Click Add new volume in the Storage section.
2. Set the size to at least 50 GB (100 GB+ for production).
3. Set the device name to /dev/sdb.
4. Check Delete on termination: No — this protects your data if the instance is terminated accidentally.
5. Optionally enable Encrypted (recommended for production).

Step 3 — Advanced details (optional but recommended)

IAM instance profile

For Standard and Enterprise tiers, attaching an instance profile enables:

• SSM Session Manager (SSH-free remote access)
• S3 backup access
• CloudWatch metrics

If you are using the CloudFormation templates as a reference, the role name follows the pattern <stack-name>-InstanceRole-<suffix>. For a manual launch, create or attach an IAM role with the following AWS managed policies:

• AmazonSSMManagedInstanceCore
• AmazonS3FullAccess (or a scoped S3 policy for your backup bucket)
• CloudWatchAgentServerPolicy

User data

Standard and Enterprise AMIs accept an optional User Data script to configure the data volume and run first-boot setup automatically. If you attach a second EBS volume (/dev/sdb), the AMI init script will detect and format it on first boot without any User Data required.

Leave User Data empty for a standard first-boot flow.

Step 4 — Launch and connect

1. Review your settings and click Launch instance.
2. Wait 2–3 minutes for the instance to reach the Running state and pass both status checks.
3. Note the Public IPv4 address from the EC2 console.

Access the staff interface:

http://<public-ip>:8080/cgi-bin/koha/mainpage.pl

Access the OPAC:

http://<public-ip>/

Default credentials are set during the Koha installer. If this is a fresh AMI launch, the installer will prompt you for admin credentials on first visit to the staff interface.

SSH access:

ssh -i your-key.pem ubuntu@<public-ip>

For full details on all connection methods (SSH, EC2 Instance Connect, SSM Session Manager), see How to Connect to Your Koha EC2 Server.

Step 5 — Assign an Elastic IP (recommended)

A standard public IP changes every time the instance stops and starts. For a production server, assign an Elastic IP:

1. In the EC2 console, go to Elastic IPs → Allocate Elastic IP address.
2. Allocate an IP and then Associate it with your new instance.
3. Use the Elastic IP in any DNS records or bookmarks.

Step 6 — Post-installation setup

Once you can reach the staff interface, follow the Post-Installation Setup guide to:

• complete the Koha web installer
• configure system preferences
• set up patron categories and item types
• configure email and SMTP

Differences from the CloudFormation path

The CloudFormation templates are recommended for most libraries because they handle all of the above automatically. The direct AMI path gives you more control but requires more manual configuration.

Troubleshooting

Instance is running but I cannot reach port 8080
Check the security group inbound rules. Port 8080 must be open. Also confirm the instance has a public IP or Elastic IP.

“No space left on device” errors after setup
The root volume may be too small. Stop the instance, resize the root EBS volume to at least 30 GB in the EC2 console, then extend the filesystem: sudo resize2fs /dev/xvda1.

I attached a data volume but Koha is still writing to the root volume
On first boot the AMI init script mounts /dev/sdb (or nvme1n1 on Nitro instances) to /mnt/koha-data. If the volume was not attached before first boot, you will need to mount it manually and update /etc/fstab. Contact KohaSupport for assistance.

SSH connection refused
Confirm port 22 is open in the security group and that you are using the correct key pair and username (ubuntu).