AWS & Deployment

Deploy Koha: Standard Tier

Step-by-step guide to deploying Koha Standard tier on AWS with automated backups and SSL support. Perfect for medium-sized libraries.

December 05, 2025 12 min read

Use this guide with the Standard Self-Service Launch Checklist This page explains the template itself. For the full end-to-end launch sequence, use the Standard Self-Service Launch Checklist alongside it.

Deploy Koha Standard tier with automated S3 backups and optional custom domains with free SSL certificates. Perfect for medium-sized libraries.

Overview

Deployment time: ~5 minutes
Best for: Medium libraries Architecture: Single EC2 instance + automated S3 backups + optional SSL

What you’ll get:

Single EC2 instance (t3.medium recommended)
Persistent data EBS volume (separate from the instance — survives AMI upgrades and instance replacement)
MySQL database running on the data volume
Automated daily S3 backups with retention policies
Optional custom domains (library.yourdomain.com)
Optional free Let’s Encrypt SSL certificates
Professional HTTPS URLs

Advantages over Free Tier:

✓ Persistent data volume — AMI upgrades don’t touch library data
✓ Automated encrypted S3 backups
✓ Custom domain support
✓ Free SSL/TLS certificates
✓ Automatic certificate renewal

Prerequisites

Before you begin:

AWS account with payment method
AWS Marketplace subscription to KohaSupport Koha ILS Standard tier
Optional: Domain name (for custom URLs with SSL)
Optional: DNS access (to create A records)

Step 1: Launch CloudFormation Template

Delivery Method: Select CloudFormation Template
Software Version: Choose latest version
Region: Select closest AWS region
Click Continue to Launch
Click Launch CloudFormation

Step 2: Configure CloudFormation Stack

Stack Details

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

Parameters

AWS Marketplace

ImageId
Auto-filled from marketplace subscription ✓

Instance Configuration

InstanceType
Choose appropriate instance type based on tier architecture:

Standard tier (ARM64): m8g.medium recommended (2 vCPU, 4 GB RAM)
Alternative (x86): t3.medium (2 vCPU, 4 GB RAM)
Larger libraries: 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
This controls the size of the data volume — the separate EBS volume that holds your MySQL database, Koha configuration, and library files. The root OS disk is always a fixed 20 GB and is separate.

Minimum: 10 GB
Recommended: 50 GB or more for a real library
The data volume persists across AMI upgrades and instance replacements

InstallLanguages
Optional comma-separated language codes:

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

Network Configuration

VpcId - Leave blank
SubnetId - Leave blank

Domain Configuration (Optional)

For first deployment, leave these as defaults. Configure domains after deployment.

EnableNameBasedVirtualHost
Default: false
Set to true only after DNS is configured

DomainName
Your domain (e.g., yourlibrary.org)
Required if using custom domains
You must own this domain and control DNS

OpacSubdomain
Default: library
Creates: library.yourlibrary.org
Public catalog URL

StaffSubdomain
Default: libadmin
Creates: libadmin.yourlibrary.org
Staff interface URL

EnableSSL
Default: false
Enable only after DNS records are propagated
Uses free Let’s Encrypt certificates

SSLEmail
Your email for certificate notifications
Required if EnableSSL is true

S3 Backup Configuration

EnableS3Backup
Default: true ✓ Recommended

BackupSchedule
Options: hourly, every-3-hours, every-6-hours, daily, weekly
Default: daily

BackupTime
24-hour format: 23:00 (11 PM)
Choose low-traffic hours

BackupRetentionDays
Default: 365 (1 year)
Range: 30-2555 days
Older backups automatically deleted

Stack Options

Add tags:

Environment: Production
Tier: Standard

Review and Launch

Review all settings
Check ☑ IAM resources acknowledgement
Click Create stack
Wait 15-25 minutes

Step 3: Review and Launch

Review all settings
Check ☑ IAM resources acknowledgement
Click Create stack
Wait 15-25 minutes

Step 4: Retrieve Access Information

Once CREATE_COMPLETE:

CloudFormation Outputs

KohaPublicCatalogURL
http://X.X.X.X:8080 - Public catalog

KohaAdminInterfaceURL
http://X.X.X.X:8443 - Staff interface

ElasticIP
Static IP for DNS configuration
Save this for domain setup

S3BackupBucket
Bucket name for automated backups

KohaAdminCredentialsPath
Parameter Store path for password

DataVolumeId
The EBS volume ID of the persistent data volume (e.g. vol-0abc123...). Keep a note of this — it is the volume that holds all your library data.

DataVolumeAvailabilityZone
The Availability Zone where the data volume was created. All future instances must use this same AZ.

DataVolumeInfo
A reminder that the data volume has DeletionPolicy: Retain — deleting the CloudFormation stack does not delete the data volume.

KohaAutomationRoleArn
ARN of the IAM role pre-configured for Koha SSM Automation runbooks. Use this as the AutomationAssumeRole parameter when running any Koha-Configure-* Automation document from AWS Systems Manager.

KohaSSMCommandDocName
Name of the internal command document used by Koha Automation runbooks (e.g. Koha-Apply-Config-OnInstance-{StackName}). Use this as the InternalCommandDocumentName parameter when running Automation docs.

ThemeBuilderActivation
Instructions for activating Koha Theme Builder™. If you launched the stack with ActivatePlugin=true, the plugin is already activated. Otherwise, follow the instructions in this output to activate after completing the Koha web installer.

Step 5: Retrieve Admin Password

Choose one method:

AWS Console

AWS Systems Manager → Parameter Store
Search for credentials path
Click parameter → Show value

AWS CLI

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

EC2 Instance Connect

# Connect to instance
# Then run:
sudo koha-passwd library

Username: koha_library

Step 6: Initial Access

Open KohaAdminInterfaceURL
Log in with credentials
Test functionality
Proceed to post-installation setup

→ Post-Installation Setup Guide

Step 7: Activate Koha Theme Builder™ (Standard)

Theme Builder is available on Standard tier. If you set ActivatePlugin=true when launching the stack, it activated automatically during bootstrap — skip this step.

If you left ActivatePlugin as false (the default), activate it after completing the Koha web installer:

Option 1 — SSM Automation (no SSH required)

Go to AWS Systems Manager → Automation
Run document: Koha-Configure-ThemeBuilder-{YourStackName} (visible in Documents → Owned by me)
Set AutomationAssumeRole to the value of KohaAutomationRoleArn from Outputs
Set InternalCommandDocumentName to the value of KohaSSMCommandDocName from Outputs
Set ApplyNow to true
Run automation

Option 2 — Session Manager CLI

# Connect to the instance via EC2 Instance Connect or Session Manager, then:
sudo /opt/kohasupport/bin/ks-plugin-install library

Note: Activate Theme Builder after completing the Koha web installer. The plugin requires Koha’s database tables to exist.

Optional: Configure Custom Domains with SSL

Want professional URLs like https://library.yourlibrary.org? Follow these steps after initial deployment.

Important: Standard uses A records pointing to the Elastic IP for custom domains. If DNS is not already ready when you try to enable SSL, SSL setup will fail. It is safer to configure domains first, wait for DNS propagation, then enable SSL on the instance using koha-setup-domains. Do not rely on a CloudFormation stack update to turn SSL on later.

Prerequisites

Domain name you own
Access to DNS management
Elastic IP from CloudFormation Outputs

Step 1: Configure DNS

At your DNS provider (Cloudflare, Route 53, etc.):

Create two A records:

Type: A
Name: library
Value: <ElasticIP from Outputs>
TTL: 300

Type: A
Name: libadmin
Value: <ElasticIP from Outputs>
TTL: 300

Step 2: Verify DNS Propagation

Wait 15-30 minutes, then test:

nslookup library.yourlibrary.org
nslookup libadmin.yourlibrary.org

Both should return your Elastic IP.

Step 3: Enable Domains and SSL

You have two options:

Option A — SSM Automation (no SSH required)

For domains only, run Koha-Configure-Domains-{StackName}:

Go to AWS Systems Manager → Automation
Choose Execute Automation → search for Koha-Configure-Domains-{StackName}
Set AutomationAssumeRole to KohaAutomationRoleArn from stack Outputs
Set InternalCommandDocumentName to KohaSSMCommandDocName from stack Outputs
Provide DomainName, OpacSubdomain, StaffSubdomain
Click Execute

For domains and SSL in one step, use Koha-Configure-SSL-{StackName} instead — it sets both domain config and requests a Let’s Encrypt certificate:

Go to AWS Systems Manager → Automation
Search for Koha-Configure-SSL-{StackName}
Set AutomationAssumeRole and InternalCommandDocumentName from Outputs (same as above)
Provide DomainName, OpacSubdomain, StaffSubdomain, SSLEmail
Set EnableSSL to true
Click Execute

DNS must be propagated before running the SSL doc. Let’s Encrypt verifies domain ownership over HTTP — if your A records aren’t live yet, the certificate request will fail. Run the Domains doc first, verify propagation, then run the SSL doc.

Option B — CLI via EC2 Instance Connect

sudo koha-setup-domains \
  --domain yourlibrary.org \
  --opac-subdomain library \
  --staff-subdomain libadmin \
  --enable-ssl \
  --ssl-email [email protected]

This will:

Configure Apache virtual hosts
Request Let’s Encrypt SSL certificates
Set up automatic renewal
Redirect HTTP → HTTPS

Step 4: Verify HTTPS Access

Test your new URLs:

OPAC: https://library.yourlibrary.org
Staff: https://libadmin.yourlibrary.org

Troubleshooting SSL

If SSL setup fails:

# Check logs
sudo tail -f /var/log/letsencrypt/letsencrypt.log
sudo tail -f /var/log/cloud-init-output.log

Common issues:

DNS not propagated → Wait longer
Port 80 blocked → Check security groups
Invalid email → Use valid address

S3 Automated Backups

What Gets Backed Up

Complete MySQL database dump (compressed)
Koha configuration files (/etc/koha/)
Zebra indexes
Custom templates and plugins
System preferences

S3 Bucket Features

Encryption: AES-256 at rest
Versioning: Enabled
Storage Class: Intelligent-Tiering
Lifecycle: Auto-deletes after retention period

Backup File Format

koha-backup-YYYY-MM-DD-HH-MM-SS.tar.gz

Example: koha-backup-2025-12-11-23-00-00.tar.gz

Complete Backup & Recovery Guide

For comprehensive backup procedures, database exports, restore testing, and migration strategies:

→ Koha Tier Migration Guide

Covers:

S3 backup verification
Database backup and restore procedures
Manual backup creation
Disaster recovery procedures
Data migration between tiers
Testing and validation

Monitoring & Maintenance

For comprehensive system monitoring, CloudWatch setup, log analysis, and maintenance schedules:

→ Monitoring & Maintenance Guide

Covers:

System health monitoring
CloudWatch alarms and dashboards
Log locations and analysis
Database performance monitoring
S3 backup verification
Automated health checks
Regular maintenance tasks
Scaling guidance

Security

For detailed security configuration, hardening, encryption, and compliance:

→ Security Best Practices Guide

Covers:

Network security and firewall rules
IAM permissions and roles
SSH key management
Data encryption (EBS, S3, in-transit)
S3 bucket security
Security monitoring and auditing
Compliance (GDPR, PCI DSS)
Incident response

Troubleshooting

For common deployment issues and solutions, see:

→ CloudFormation Troubleshooting Guide

Includes solutions for:

Stack creation failures
Instance access issues
S3 backup problems
SSL certificate issues
Domain configuration
And more…

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

Upgrading to a New Koha AMI Version

Because library data lives on a separate persistent EBS volume (not on the instance root disk), upgrading to a newer Koha AMI version is straightforward and safe — your data is never at risk.

What happens on an AMI upgrade

CloudFormation replaces the EC2 instance with a new one running the updated AMI.
The new instance boots, reads the data volume ID from AWS Systems Manager Parameter Store, and reattaches the same data volume automatically.
MySQL starts from the existing data directory on the attached volume — all records, patrons, and configuration are untouched.
Koha starts normally.

How to upgrade

Subscribe to (or confirm your subscription covers) the newer AMI version in AWS Marketplace.
Open CloudFormation in the AWS Console and select your Koha stack.
Click Update → Use current template.
Update the ImageId parameter to the new AMI ID.
Proceed through the wizard and apply the change.
CloudFormation will replace the instance. The data volume reattaches automatically.
Verify the OPAC and staff interface are running after the update completes.

Note: Keep a note of your DataVolumeId output. You do not need it for a routine AMI upgrade, but it is useful if you ever need to inspect or manually reattach the volume.

S3 backups still apply. Even though the data volume is persistent, continue using S3 backups as your safety net against accidental data loss, corruption, or volume failure.

Upgrade to Enterprise

Need high availability and scalability?

Enterprise is KohaSupport’s more resilient AWS architecture for libraries that need stronger recovery options, scaling capacity, and operational resilience. Managed implementation help is available separately. If you’re considering moving from Standard to Enterprise, book a consultation to discuss your resilience requirements and custom architecture.

For detailed migration procedures with database backup and restore: