Deploy Koha Enterprise tier with multi-AZ high availability, Aurora Serverless database, Application Load Balancer, and auto-scaling. Perfect for large libraries.

Overview

Deployment time: 10-15 minutes
Best for: Large libraries Architecture: Multi-AZ HA with Auto Scaling + Aurora + ALB + EFS

What you’ll get:

  • Multi-server deployment in multiple Availability Zones
  • Aurora Serverless v2 database (auto-scaling)
  • Application Load Balancer with SSL
  • Auto Scaling Group (scale based on traffic)
  • EFS shared storage across instances
  • S3 automated backups
  • Enterprise-grade 99.9% uptime

Advantages over Standard tier:

  • ✓ Zero-downtime updates
  • ✓ Automatic failover across zones
  • ✓ Database auto-scaling (0.5-16 ACU)
  • ✓ Handle traffic spikes automatically
  • ✓ True high availability

Prerequisites

Before you begin:

  • AWS account with payment method
  • AWS Marketplace subscription to KohaSupport Koha ILS Enterprise tier
  • Domain name (required for SSL)
  • DNS access (to create CNAME records)
  • ACM SSL certificate (must request before deployment)

⚠️ Important: Unlike Basic/Standard, Enterprise requires SSL certificate setup before launching CloudFormation.

We recommend you complete this step before launching CloudFormation, otherwise you will need to update the stack later with the certificate ARN.

Request Certificate

  1. Go to AWS Certificate Manager (ACM)
  2. Region: Same region as deployment
  3. Click Request certificate
  4. Certificate type: Public
  5. Domain names:
    • *.yourlibrary.org (wildcard)
    • yourlibrary.org (apex)
  6. Validation: DNS validation
  7. Click Request

Validate Certificate

ACM will provide DNS records, for example:

Type: CNAME
Name: _abc123xyz.yourlibrary.org
Value: _xyz789abc.acm-validations.aws

Add these to your DNS provider.

Wait for Validation

  • Status will change: Pending → Issued (this might take a few minutes)

Copy Certificate ARN

From ACM console, copy the Certificate ARN, e.g.:

arn:aws:acm:us-east-1:123456789:certificate/abc-123-xyz

You’ll need this for when configuring the CloudFormation stack.

Step 1: Launch CloudFormation Template

  1. Delivery Method: Select CloudFormation Template
  2. Software Version: Choose latest version
  3. Region: Select same region as ACM certificate
  4. Click Continue to Launch
  5. Click Launch CloudFormation

Step 2: Configure CloudFormation Stack

Stack Details

Stack name
Enter: koha-enterprise-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:

  • Enterprise tier (ARM64): m8g.large recommended (2 vCPU, 8 GB RAM)
  • Minimum (ARM64): m8g.medium (2 vCPU, 4 GB RAM)
  • High performance (ARM64): m8g.xlarge (4 vCPU, 16 GB RAM)
  • Alternative (x86): t3.medium, t3.large, or t3.xlarge

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 to any instance in the Auto Scaling Group. The Enterprise template automatically creates an EC2 Instance Connect Endpoint in your VPC. See Using EC2 Instance Connect below for instructions.

EBSVolumeSize

  • Minimum: 50 GB
  • Recommended: 100 GB or more

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

Auto Scaling Configuration

ASGMinSize
Minimum: 2 (one per AZ)
Cannot be less than 2 for HA

ASGMaxSize
Maximum: 5 or more
Scales up during high traffic

ASGDesiredCapacity
Normal state: 2
Typical: Same as MinSize

Network Configuration

VpcId
Select your VPC or leave blank for default

PublicSubnetA
Select public subnet in AZ-a

PublicSubnetB
Select public subnet in AZ-b

PrivateSubnetA
Select private subnet in AZ-a

PrivateSubnetB
Select private subnet in AZ-b

💡 Subnet requirements:

  • Public subnets: For ALB (internet-facing)
  • Private subnets: For EC2 instances (secure)
  • Must be in different AZs
  • Leave all blank for default VPC setup

Aurora Database Configuration

AuroraMinCapacity
Default: 0.5 ACU
Minimum compute capacity (1 ACU = 2 GB RAM)

AuroraMaxCapacity
Default: 4 ACU
Maximum compute capacity
Recommended: 2 (small), 4 (medium), 8 (large)

DatabaseUsername
Default: kohaadmin

DatabasePassword
Auto-generated secure password ✓

💡 ACU sizing guide:

  • 0.5-2 ACU: Small libraries (< 5K patrons)
  • 2-4 ACU: Medium libraries (5K-15K patrons)
  • 4-8 ACU: Large libraries (15K+ patrons)

EFS Configuration

EFSProvisionedThroughput
Default: 10 MiB/s
Range: 1-1024 MiB/s

EFSPerformanceMode
Options: generalPurpose, maxIO
Default: generalPurpose

Load Balancer Configuration

CertificateArn
Required: Paste ARN from Step 0
Format: arn:aws:acm:us-east-1:...

DomainName
Your domain: yourlibrary.org

OpacSubdomain
Default: library
Creates: library.yourlibrary.org

StaffSubdomain
Default: libadmin
Creates: libadmin.yourlibrary.org

HealthCheckPath
Default: /cgi-bin/koha/mainpage.pl

S3 Backup Configuration

EnableS3Backup
Default: true ✓ Required

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

BackupTime
24-hour format: 23:00

BackupRetentionDays
Default: 365 (1 year)

Stack Options

Add tags:

  • Environment: Production
  • Tier: Enterprise
  • HA: True

Review and Launch

  1. Review all settings
  2. Check ☑ IAM resources acknowledgement
  3. Click Create stack
  4. Wait 30-45 minutes

Step 3: Review and Launch

  1. Review all settings
  2. Check ☑ IAM resources acknowledgement
  3. Click Create stack
  4. Wait 30-45 minutes for deployment

Monitor progress:

  • Watch Events tab for real-time status
  • Check Resources tab to see infrastructure being created
  • Status: CREATE_IN_PROGRESS → CREATE_COMPLETE

Step 4: Retrieve Access Information

Once CREATE_COMPLETE:

CloudFormation Outputs

KohaPublicCatalogURL
https://library.yourlibrary.org - Public catalog

KohaAdminInterfaceURL
https://libadmin.yourlibrary.org - Staff interface

LoadBalancerDNS
ALB DNS name for CNAME records
Example: koha-alb-123456789.us-east-1.elb.amazonaws.com

AuroraClusterEndpoint
Database writer endpoint

AuroraReaderEndpoint
Database reader endpoint (read replicas)

EFSFileSystemId
Shared storage ID

S3BackupBucket
Automated backup bucket

KohaAdminCredentialsPath
Parameter Store path for Koha password

DatabaseCredentialsSecret
Secrets Manager ARN for Aurora password

Step 5: Configure DNS

Critical: Create CNAME records at your DNS provider.

Required DNS Records

Type: CNAME
Name: library
Value: <LoadBalancerDNS from Outputs>
TTL: 300

Type: CNAME
Name: libadmin
Value: <LoadBalancerDNS from Outputs>
TTL: 300

Verify DNS Propagation

Wait 15-30 minutes:

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

Both should return ALB IP addresses.

Step 6: Retrieve Admin Password

Choose one method:

AWS Console

  1. AWS Systems Manager → Parameter Store
  2. Search for credentials path
  3. Click parameter → Show value

AWS CLI

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

EC2 Instance Connect

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

Username: koha_library

Step 7: Initial Access

  1. Open KohaPublicCatalogURL (HTTPS)
  2. Log in with credentials
  3. Test functionality across both interfaces
  4. Proceed to post-installation setup

→ Post-Installation Setup Guide

Architecture Details

High Availability Components

Application Load Balancer (ALB)

  • Health checks every 30 seconds
  • Routes to healthy instances only
  • SSL termination
  • Sticky sessions for staff interface

Auto Scaling Group (ASG)

  • Min 2 instances (one per AZ)
  • Scales based on CPU/memory
  • Automatic replacement of failed instances
  • Zero-downtime rolling updates

Aurora Serverless v2

  • Auto-scaling capacity (0.5-16 ACU)
  • Multi-AZ replication
  • Automatic failover (< 30 seconds)
  • Point-in-time recovery (35 days)
  • Continuous backups to S3

EFS (Elastic File System)

  • Shared storage across instances
  • Automatic replication across AZs
  • Scales automatically
  • Stores: uploads, plugins, custom templates

Traffic Flow

User → Route 53 (DNS)
     → ALB (HTTPS)
     → Target Group (Health Check)
     → EC2 Instance (AZ-a or AZ-b)
     → Aurora (Database)
     → EFS (Shared Files)

Failure Scenarios

Instance failure:

  • ALB stops routing to failed instance
  • ASG launches replacement automatically
  • No downtime (other instance handles traffic)

AZ failure:

  • ALB routes all traffic to healthy AZ
  • ASG launches replacements in healthy AZ
  • Aurora fails over to standby (< 30s)

Database failure:

  • Aurora fails over to replica
  • Application reconnects automatically
  • < 30 second disruption

Monitoring & Maintenance

For comprehensive Enterprise tier monitoring, including ALB metrics, Aurora performance, Auto Scaling insights, and maintenance procedures:

→ Monitoring & Maintenance Guide

Covers:

  • CloudWatch dashboards and alarms
  • ALB, ASG, Aurora, and EFS metrics
  • Log aggregation and analysis
  • Performance Insights for Aurora
  • Auto Scaling policies
  • Regular maintenance tasks
  • Capacity planning

Enterprise-specific considerations:

  • Monitor ALB target health across all instances
  • Track Aurora ACU (Aurora Capacity Unit) usage
  • Set up alarms for 5xx errors on ALB
  • Monitor EFS throughput and client connections
  • Review Auto Scaling events and policies

Backup & Recovery

What Gets Backed Up:

  • Aurora: Automatic continuous backups with 35-day retention and point-in-time recovery
  • S3 Backups: Koha configuration, custom templates, plugins, and system preferences
  • EFS: Shared file storage snapshots

For complete backup and disaster recovery procedures:

→ Koha Tier Migration Guide

Covers:

  • Aurora point-in-time recovery
  • S3 backup verification and restoration
  • Database export/import procedures
  • Disaster recovery testing
  • Data migration strategies
  • Cross-region backup strategies

Scaling & Performance

Auto Scaling handles instance count automatically based on CPU and memory.

Aurora Serverless scales database capacity automatically based on workload.

For detailed scaling configuration and performance optimization:

→ Monitoring & Maintenance Guide

Manual scaling when needed:

# Update ASG desired capacity
aws autoscaling set-desired-capacity \
  --auto-scaling-group-name koha-asg \
  --desired-capacity 4

# Modify Aurora capacity limits
aws rds modify-db-cluster \
  --db-cluster-identifier your-cluster \
  --serverless-v2-scaling-configuration MinCapacity=1.0,MaxCapacity=8.0

Security

For comprehensive Enterprise security configuration, including network isolation, IAM roles, encryption, and compliance:

→ Security Best Practices Guide

Enterprise tier security includes:

  • Network Security: Multi-layer security groups (ALB → Instances → Aurora → EFS)
  • IAM Roles: Instance role, Auto Scaling role, and service-linked roles
  • Encryption: ALB (TLS 1.2+), EBS, Aurora, EFS, S3, Secrets Manager
  • Access Control: No direct SSH, use Session Manager or EC2 Instance Connect
  • Compliance: GDPR, PCI DSS, HIPAA-eligible infrastructure

Key security features:

  • ALB only allows 80/443 from internet
  • Instances only accept traffic from ALB
  • Aurora only accessible from application instances
  • All data encrypted at rest and in transit
  • Secrets stored in AWS Secrets Manager

Troubleshooting

For common deployment issues and solutions, see:

→ CloudFormation Troubleshooting Guide

Includes solutions for:

  • Stack creation failures
  • Load balancer 502/503 errors
  • Aurora database connection issues
  • Instance health check failures
  • Auto Scaling Group problems
  • Performance optimization
  • And more…

Creating SSH Keys

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

Create Key Pair in AWS Console

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

Using Your Key

# Connect to any instance in the Auto Scaling Group
# Mac/Linux
chmod 400 koha-enterprise-key.pem
ssh -i koha-enterprise-key.pem ubuntu@<instance-ip>

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

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

Using EC2 Instance Connect

The Enterprise CloudFormation template automatically creates an EC2 Instance Connect Endpoint, so you can immediately use browser-based SSH access without any additional setup.

Option 1: AWS Console (Browser-based)

  1. Go to EC2 Console → Auto Scaling Groups
  2. Select your Koha Auto Scaling Group
  3. Click Instance management tab
  4. Select any instance from the list
  5. Click Connect button
  6. Choose EC2 Instance Connect tab
  7. Connection type: Select Connect using EC2 Instance Connect Endpoint
  8. EC2 Instance Connect Endpoint: The endpoint created by CloudFormation will be auto-selected
  9. Username: Enter ubuntu
  10. Click Connect

Option 2: AWS CLI

# List instances in your Auto Scaling Group
aws autoscaling describe-auto-scaling-groups \
  --auto-scaling-group-names koha-enterprise-library-ASG \
  --query 'AutoScalingGroups[0].Instances[*].InstanceId' \
  --output text

# Connect to any instance using Instance Connect Endpoint
aws ec2-instance-connect ssh \
  --connection-type eice \
  --os-user ubuntu \
  --instance-id i-0123456789abcdef0

Note: Replace i-0123456789abcdef0 with any instance ID from your Auto Scaling Group. The CLI automatically uses the Instance Connect Endpoint created by the template.

Cost

  • Pricing: EC2 Instance Connect Endpoint charges apply per hour
  • Calculate costs: Use the AWS Pricing Calculator to estimate costs for your region
  • Note: One endpoint serves all instances in the Auto Scaling Group
  • Tip: Search for “EC2 Instance Connect Endpoint” in the calculator for current pricing

Zero-Downtime Updates

Rolling Update Strategy

# Update launch template
aws autoscaling update-auto-scaling-group \
  --auto-scaling-group-name koha-asg \
  --launch-template LaunchTemplateId=lt-xxx,Version=2

# Perform rolling replacement
aws autoscaling start-instance-refresh \
  --auto-scaling-group-name koha-asg \
  --preferences MinHealthyPercentage=50,InstanceWarmup=300

Process:

  1. Launch new instance with updated config
  2. Wait for health check pass
  3. Terminate old instance
  4. Repeat until all replaced

Cost Optimization

Right-Sizing

Compute:

  • Monitor CPU/memory for 2 weeks
  • Downsize if consistently < 40%
  • Use smaller instance types if possible

Aurora:

  • Review ACU utilization
  • Adjust min/max capacity
  • Consider Graviton instances

EFS:

  • Review throughput metrics
  • Switch to bursting if low usage
  • Use Lifecycle policies for infrequent access

Reserved Capacity

1-year commitment:

  • ~40% savings on EC2
  • ~35% savings on RDS
  • Consider for stable workloads

Additional Resources

Get Support

Need help?

Last Updated: December 2025