Deploy Koha: Free & Basic Tier

Deploy a single-instance Koha server on AWS for small libraries. This guide covers both Free and Basic tier deployments, which use identical CloudFormation templates.

Overview

Deployment time: ~5 minutes
Best for: Small libraries
Architecture: Single EC2 instance with local MySQL database

What you’ll get:

Single EC2 instance (t3.medium for free tier, m8g.medium recommended for basic tier)
MySQL database running locally on the instance
Elastic IP for static address
Port-based HTTP URLs (http://X.X.X.X:8080 and :8443)
EC2 Instance Connect for SSH access

Limitations:

No SSL/HTTPS support
No automated cloud backups (manual local backups only)
No high availability
No custom domain support

Prerequisites

Before you begin:

AWS account with payment method
AWS Marketplace subscription to KohaSupport Koha ILS (Free or Basic tier)
Basic familiarity with AWS console (helpful but not required)

Step 1: Launch CloudFormation Template

Delivery Method: Select CloudFormation Template
Software Version: Choose latest version
Region: Select closest AWS region (e.g., us-east-1, eu-west-1)
Click Continue to Launch
Click Launch CloudFormation

Step 2: Configure CloudFormation Stack

Stack Details

Stack name
Enter: koha-basic-library or your library name (e.g. springfield-library)

Parameters

AWS Marketplace

ImageId
Auto-filled from your marketplace subscription ✓

Instance Configuration

InstanceType
Choose appropriate instance type based on tier architecture:

Free tier (x86): t3.small or t3.medium recommended
Basic tier (ARM64): m8g.medium recommended (2 vCPU, 8 GB RAM)
Larger collections: m8g.large (ARM64) or t3.large (x86)

KeyPairName
Optional SSH key pair for traditional SSH access:

Leave blank to use EC2 Instance Connect only (recommended)
Or enter name of an existing EC2 key pair
To find existing keys: EC2 Console → Network & Security → Key Pairs
To create a new key: See Creating SSH Keys below

Note: If left blank, you can use EC2 Instance Connect for browser-based SSH access. The templates configure security groups to allow Instance Connect traffic, but you must manually create an EC2 Instance Connect Endpoint in your VPC. See Setting Up EC2 Instance Connect Endpoint below for instructions.

EBSVolumeSize
Disk space in GB:

Minimum: 20 GB
Recommended: 50 GB for 50,000+ items
Stores database, Koha files, and backups

InstallLanguages
Optional comma-separated language codes:

Leave blank for English only
Example: es-ES,fr-FR,de-DE (Spanish, French, German)
See Available Translations for complete list of 100+ supported languages

Network Configuration

VpcId
Leave blank to use default VPC (recommended)

SubnetId
Leave blank for automatic subnet selection

Stack Options

Add tags for organization (optional):

Environment: Production
Library: Your Library Name
Department: Library Services

Review and Launch

Review all settings
Check ☑ “I acknowledge that AWS CloudFormation might create IAM resources”
Click Create stack
Wait 10-15 minutes for deployment

Monitor progress:

Watch Events tab for real-time status
Check Resources tab to see what’s being created
Status will show CREATE_IN_PROGRESS → CREATE_COMPLETE

Step 3: Retrieve Access Information

Once stack status shows CREATE_COMPLETE:

Go to CloudFormation console
Select your stack
Click Outputs tab

Available Outputs

KohaPublicCatalogURL
Public OPAC interface: http://X.X.X.X:8080
Share this URL with your library patrons

KohaAdminInterfaceURL
Staff interface: http://X.X.X.X:8443
Use this for cataloging, circulation, and administration

KohaServerIPAddress
Static Elastic IP address (won’t change if instance restarts)

KohaAdminCredentialsPath
Path to password in Systems Manager Parameter Store
Format: /koha/your-stack-name/credentials

Step 4: Retrieve Admin Password

Choose one of these methods:

Method 1: AWS Console (Recommended)

Go to AWS Systems Manager
Click Parameter Store in left menu
Search for your credentials path (from Outputs tab)
Click the parameter name
Click Show value to reveal password

Note: Requires IAM permission ssm:GetParameter

Method 2: AWS CLI

aws ssm get-parameter \
  --name /koha/your-stack-name/credentials \
  --with-decryption \
  --query 'Parameter.Value' \
  --output text

Method 3: EC2 Instance Connect

Go to EC2 Console
Select your Koha instance
Click Connect → EC2 Instance Connect
Username: ubuntu
Click Connect
Run command:

sudo koha-passwd library

This displays the username and password for your Koha site.

Step 5: Log In to Koha

Open KohaAdminInterfaceURL from Outputs tab
Username: koha_library (default)
Password: Retrieved from Step 4
You’re in! Proceed to post-installation setup

Creating SSH Keys

If you want to use traditional SSH instead of EC2 Instance Connect:

Create Key Pair in AWS Console

Go to EC2 Console
Navigate to Network & Security → Key Pairs
Click Create key pair
Name: Enter a memorable name (e.g., koha-ssh-key)
Key pair type: Choose RSA
Private key file format:
- .pem for Mac/Linux/Windows (OpenSSH)
- .ppk for PuTTY (Windows)
Click Create key pair
Save the downloaded file securely (you can’t download it again)

Using Your Key

# Mac/Linux
chmod 400 koha-ssh-key.pem
ssh -i koha-ssh-key.pem ubuntu@<instance-ip>

# Windows (PowerShell with OpenSSH)
ssh -i koha-ssh-key.pem ubuntu@<instance-ip>

Important: The key pair must be created in the same AWS region where you’re deploying Koha.

Setting Up EC2 Instance Connect Endpoint

If you didn’t configure a KeyPair and want to use EC2 Instance Connect for browser-based SSH access, you must create an EC2 Instance Connect Endpoint. The CloudFormation templates configure security groups to allow Instance Connect traffic, but do not create the endpoint itself.

Why You Need This

Without endpoint: Cannot use EC2 Instance Connect from AWS Console
With endpoint: Browser-based SSH access from EC2 Console (no key file needed)
Security: Instance Connect endpoints provide secure access to instances in private subnets

Create Instance Connect Endpoint

Go to VPC Console (not EC2 Console)
In left navigation, scroll down to Virtual private cloud section
Click Endpoints
Click Create endpoint
Configure endpoint:
- Name: koha-instance-connect-endpoint
- Service category: Select EC2 Instance Connect Endpoint
- VPC: Select the VPC where your Koha instance is deployed
- Security groups: Select the security group created by CloudFormation (look for stack name in security group name)
- Subnet: Select the subnet where your instance is running
Click Create endpoint
Wait 2-3 minutes for endpoint to become Available

Using Instance Connect After Endpoint Creation

Option 1: AWS Console (Browser-based)

Go to EC2 Console
Select your Koha instance
Click Connect button
Choose EC2 Instance Connect tab
Connection type: Select Connect using EC2 Instance Connect Endpoint
EC2 Instance Connect Endpoint: Select the endpoint you created
Username: Enter ubuntu
Click Connect

Option 2: AWS CLI

# Get your instance ID from EC2 Console or CloudFormation Outputs
aws ec2-instance-connect ssh \
  --connection-type eice \
  --os-user ubuntu \
  --instance-id i-0123456789abcdef0

Note: Replace i-0123456789abcdef0 with your actual instance ID. The CLI automatically selects the appropriate Instance Connect Endpoint in the same VPC.

Cost

Pricing: EC2 Instance Connect Endpoint charges apply per hour
Calculate costs: Use the AWS Pricing Calculator to estimate costs for your region
Alternative: Use SSH keys (free, but requires key management)
Tip: Search for “EC2 Instance Connect Endpoint” in the calculator for current pricing

Troubleshooting

Can’t find Instance Connect Endpoint option:

Ensure you’re in VPC Console, not EC2 Console
Check your AWS region supports EC2 Instance Connect Endpoints
Verify you have permission ec2:CreateInstanceConnectEndpoint

Connection fails:

Verify endpoint status is Available
Confirm endpoint is in same VPC and subnet as instance
Check security group allows Instance Connect traffic (templates configure this automatically)
Ensure instance is running and status checks passed