How to Deploy Koha Library System from AWS Marketplace with CloudFormation
This guide explains how to deploy, secure, monitor, and manage the Koha ILS using the AWS CloudFormation template.
1. Subscribe to the Koha AMI Product
Subscribe to the desired Koha Library System AMI by KohaSupport on the AWS Marketplace. You can launch directly from the subscription page or via the Marketplace console.
- Via the Subscription Page:
- Click “Continue to Subscribe” and then “Continue to Configuration”.
- Select the fulfilment option (CloudFormation Template), choose the software version and desired region, then click “Continue to Launch”.
- Review the launch details and click “Launch”.
- Via the Marketplace Console:
- Go to AWS Marketplace > Manage Subscriptions.
- Find the Koha Library System AMI by KohaSupport.
- Under “Agreements”, click “Actions” > “Launch CloudFormation Template”.
- Select the fulfilment option (CloudFormation Template), choose the software version and region, then click “Continue to Launch”.
- Review the launch details and click “Launch”.
2. Launch the CloudFormation Stack
Optional. Name of an existing EC2 KeyPair to enable SSH access to the instance. If you don’t already have a key pair, create one in the EC2 Console first. To find available key pairs, go to EC2 Console > Network & Security > Key Pairs. Leave blank to use EC2 Instance Connect for SSH access.Step 1: Create stack
- Leave the default settings as they are.
- Set Prepare template to Choose an existing template.
- Set Template source to Amazon S3 URL.
- The template URL should already be pre-filled with the Koha CloudFormation template.
- Click Next.
Step 2: Specify stack details
- Enter a name for your stack (e.g.,
KohaLibrarySystem
). - ImageID: This will be pre-filled from your marketplace subscription.
- InstanceType: You can specify any valid EC2 instance type. Leave blank to use the default:
t3a.medium
for x86_64t4g.medium
for ARM64
- EBSVolumeSize: Specify the size of the Elastic Block Store (EBS) volume in GiB. This is the disk space allocated for the Koha server. The minimum size is 20GiB.
- KeyPairName: Optional. Enter the name of an existing key-pair if you want to access the server remotely via SSH. SSH access via the EC2 Instance Connect console is enabled by default.
- VpcId / SubnetId: Optional. Leave blank to use the default VPC, otherwise you can specify a valid VPC ID and subnet.
- Click Next.
Step 3: Configure stack options
- Leave default options or add tags for identification and cost tracking.
- Check the box to acknowledge IAM resource creation.
- Click Next.
Step 4: Review
- Verify all stack details and parameter values.
- Click Submit to deploy the CloudFormation stack.
3. Retrieve the Outputs
Once your stack has finished deploying, go to the “Outputs” tab in the CloudFormation console. You will see the following:
- KohaAdminInterfaceURL: Web address for the Koha Staff Interface (also called the Admin Interface). Use this to complete the initial setup and to manage your library’s catalog, patrons, circulation, and system settings.
- KohaPublicCatalogURL: Koha OPAC (Online Public Access Catalog) Interface URL. This is what your library users will see.
- KohaServerIPAddress: The static public IP address assigned to your Koha server. Use this address to access the Koha Staff and OPAC web interfaces.
- KohaServerAutoScalingGroup: The name of the Auto Scaling Group managing your Koha server. This group ensures high availability by automatically maintaining one running instance at all times.
- KohaAdminCredentialsPath: Path to the securely stored credentials in AWS Systems Manager Parameter Store. This contains your Koha administrator username and password. To retrieve it via the AWS Console: go to ‘Systems Manager’ > ‘Parameter Store’, search for this path, and click ‘Show’ to view the decrypted value. You can also retrieve the username and password by connecting to the instance via EC2 Instance Connect and running the command ‘sudo koha-passwd library’.
4. Security Best Practices for SSH Access
If you want to enable remote SSH access, secure it by doing the following:
Option 1: Update the Security Group
- Go to EC2 > Security Groups
- Locate the security group created by the CloudFormation template
- Edit inbound rules and allow SSH traffic from your desired IP address/CIDR block. We recommend you limit the range of IP addresses that can access your server and to delete the rule when it is not in use.
5. Retrieving the Koha Administrator Password
You will need the Koha administrator password to log in to the Koha staff interface and complete the post-installation setup.
Via AWS Systems Manager (recommended):
- Go to the AWS Systems Manager console.
- Navigate to Parameter Store.
- Search for the parameter using the path shown in the CloudFormation Outputs (
KohaAdminCredentialsPath
). - Click on the parameter to view its details.
- Click “Show value” to reveal the Koha admin password.
- Ensure you have the necessary IAM permissions to view SSM parameters.
- If you do not see the password, confirm your IAM role has
ssm:GetParameter
permissions.
- If you do not see the password, confirm your IAM role has
Via EC2 Instance Connect:
-
-
- Go to the AWS EC2 console.
- Select your instance and click “Connect” > “EC2 Instance Connect”.
- Enter the username
ubuntu
and click “Connect”.
-
- Once connected, run the following command:
sudo koha-passwd library
This will display the administrator username and password for the default Koha site (library
).
Use the displayed credentials to log in to the Koha staff interface at the URL provided in the CloudFormation Outputs (KohaAdminInterfaceURL
).
Via SSH Remote Access:
You can connect to the Koha server remotely via SSH using the following command:
ssh -i /path/to/your-key.pem ubuntu@<PublicIP>
Replace /path/to/your-key.pem
with your actual key file path and <PublicIP>
with the instance’s public IP. You must ensure that the security group of your Koha server allows SSH traffic from your IP address or CIDR block.
6. Data Security and Encryption
Location of All Sensitive Information Saved by Customers
- Koha Admin Password: Stored in AWS Systems Manager (SSM) Parameter Store at the path shown in the CloudFormation Outputs (
KohaAdminCredentialsPath
). - Database Data: Stored on the instance’s Amazon EBS volume at
/var/lib/mysql/
. - Koha Backups: Daily backups are saved to
/var/spool/koha/library/
on the instance. - Configuration Files: Koha and system configuration files are stored under
/etc/koha/
and/etc/mysql/
.
Detailed Explanation of All Data Encryption Configurations Used in Your Product
- Amazon EBS Encryption: All EBS volumes are encrypted using AWS-managed KMS keys by default.
- SSM Parameter Encryption: All SSM parameters (including admin credentials) are encrypted at rest using AWS-managed KMS keys.
- In-Transit Encryption: All communication with AWS APIs (including SSM) uses TLS.
Step-by-Step Instructions for Rotating Cryptographic Keys
EBS Volume Encryption Key Rotation:
- Go to AWS Key Management Service (KMS) > Customer managed keys.
- Select the key used for EBS (default is AWS-managed).
- Use the “Rotate key” option or create a new key.
- Re-encrypt the volume using the new key (requires snapshot and restore).
SSM Parameter Encryption Key Rotation:
- Go to AWS KMS > Customer managed keys.
- Rotate the key or create a new one.
- Update the SSM parameter to use the new key (only needed if using a customer-managed key).
Koha Admin Password Rotation:
- Reboot the instance to automatically rotate the password (new password is stored in SSM),
OR - Manually update the password by connecting to MySQL and running:
mysql -u root -e
"ALTER USER 'koha_library'@'localhost' IDENTIFIED BY '{{ NEW_KOHA_PASSWORD }}'; FLUSH PRIVILEGES;"
Instructions on How Users Can Decrypt Necessary Data
Koha Admin Password:
- Go to AWS Systems Manager > Parameter Store.
- Search for the parameter using the path from the CloudFormation Outputs (
KohaAdminCredentialsPath
). - Click “Show value” (requires appropriate IAM permissions).
Backups:
- Koha does not encrypt backups natively.
- If the EBS volume is encrypted, backups stored on it are encrypted at rest automatically.
Monitoring and Health Assessment
7. Monitoring and Health Assessment
- Web Access:
- Visit the Staff (http://KOHA-INSTANCE-IP-ADDRESS:8080) and OPAC (http://KOHA-INSTANCE-IP-ADDRESS:80) URLs from the CloudFormation Outputs.
- Instance Health:
- Use AWS EC2 > Instances to check instance status checks.
- Service Status:
- Connect via EC2 Instance Connect or SSH.
- Run:
systemctl status apache2
(Web server)systemctl status mysql
(Database)koha-worker --status library
(Koha background jobs)koha-plack --status library
(Koha Plack application server)
- CloudWatch Monitoring:
- Go to AWS CloudWatch > Metrics > EC2 for CPU, memory, and disk.
- Set up alarms for high CPU, low disk, or failed status checks.
- Log Files:
- Application logs:
/var/log/koha/
- System logs:
/var/log/syslog
and/var/log/mysql/
- Application logs:
8. CloudFormation Deployment Details
Purpose for AWS IAM Roles and Policies
- EC2 Instance Role:
- Allows the instance to perform actions such as:
ssm:PutParameter
– Write SSM parametersec2:AssociateAddress
– Associate Elastic IPs
- IAM Policy: Grants least-privilege access necessary for the above actions.
Purpose and Location of Each Key Created
- EBS Encryption Key:
- AWS-managed KMS key, used to encrypt EBS volumes
- Located in AWS KMS > AWS managed keys
- SSM Parameter Key:
- AWS-managed KMS key, used to encrypt SSM parameters
- Located in AWS KMS > AWS managed keys
Network Configuration Details
- Default VPC/Networking:
- If no VPC/Subnet is specified, a new VPC and subnet are created automatically
- Ports Opened:
80
– OPAC8080
– Staff Interface22
– SSH (optional, restricted bySSHAccessCIDR
)
- Multi-Resource Communication:
- All resources (EC2, SSM) are placed in the same VPC and security group
- Allows internal communication by default
- For custom VPCs, ensure subnets have internet access or SSM VPC endpoints
Detailed Guide on How Applications Are Launched and Configured to Communicate in Multi-Resource Deployments
- CloudFormation Launch:
- Creates EC2 instance with IAM role and security group
- Koha software is automatically started on boot
- Daily Koha backups saved to
/var/spool/koha/library/
- SSM Parameter Store:
- Admin credentials and configuration details are stored securely
- Instance has permissions to update parameters during password rotation
Complete Data Encryption Configuration Details
- Amazon EBS: All volumes are encrypted at rest using AWS-managed KMS keys
- SSM Parameter Store: All parameters are encrypted at rest using AWS-managed KMS keys
- In-Transit: All AWS API calls use TLS encryption
- Koha Application:
- Passwords and sensitive data are encrypted using bcrypt hashing
- EBS volumes can optionally use customer-managed KMS keys for added security
- HTTPS can be configured manually for secure access
- Setup instructions available in the knowledge base: https://kohasupport.com/knowledge-base/
Pricing Breakdown and AWS Service Quotas
9. Pricing Breakdown and AWS Service Quotas
In addition to the software costs, there may be AWS service costs associated with running the Koha Library System. These costs are charged by AWS for resource usage and are not included in the Koha subscription.
- AWS Systems Manager Parameter Store:
- The CloudFormation template uses AWS Systems Manager Parameter Store to securely store the Koha admin password.
- This incurs no additional cost for standard parameters.
- See https://aws.amazon.com/systems-manager/pricing/ for details.
- Elastic IP Address:
- If you choose to associate an Elastic IP with your instance, there is a small hourly charge when it is not associated with a running instance.
- See https://aws.amazon.com/vpc/pricing/ for details.
- AWS Free Tier:
- 750 hours/month for
t3.micro
andt2.micro
instances. See https://aws.amazon.com/free/ for details. - 30 GB EBS storage/month. See https://aws.amazon.com/ebs/pricing/ for details.
- 750 hours/month for
- Additional Costs:
- Exceeding free tier limits (larger instance, more storage, or data transfer) will incur standard AWS charges.
- Managing Quotas:
- Monitor usage in AWS Billing > Cost Explorer.
- Use AWS Service Quotas to request increases if needed.
10. Backup and Recovery
- Daily Backups:
- Saved to
/var/spool/koha/library/
on the instance. - Can be copied via SSH or downloaded from the Koha staff interface.
- Saved to
- Restore:
- Launch a new instance.
- Upload backup file.
- Restore using Koha command-line tools:
sudo koha-restore sqldump configdump
11. Notes
- No third-party services are used.
- HTTPS is not pre-configured but can be added manually.
For further details, see the CloudFormation Outputs tab after deployment and refer to the AWS documentation for managing IAM, KMS, and SSM encryption.
12. Troubleshooting Common Issues
- Instance Not Starting:
- Check CloudFormation stack events for deployment errors.
- Verify IAM permissions for the deployment role.
- Ensure the selected subnet has internet access.
- Cannot Access Koha Interface:
- Verify security group rules allow traffic on ports
80
and8080
. - Check instance status and system logs via the EC2 console.
- Confirm the instance has successfully completed initialization – it takes a few minutes before the server is up and running.
- Change the instance type to a larger one – some
- Verify security group rules allow traffic on ports
- Password Retrieval Issues:
- Ensure your IAM user or role has
ssm:GetParameter
permissions. - Check that the parameter exists at the specified SSM path.
- Verify the parameter was created during stack deployment.
- Ensure your IAM user or role has
- Backup Failures:
- Check disk space:
df -h /var/spool/koha/library/
- Verify MySQL service is running:
systemctl status mysql
- Review Koha logs:
tail -f /var/log/koha/library/*
- Check disk space:
- Support and Documentation:
- Visit our knowledge base: https://kohasupport.com/knowledge-base/
- Official Koha documentation: https://koha-community.org/documentation/
- AWS CloudFormation documentation: https://docs.aws.amazon.com/cloudformation/
13. Log-in to your OPAC interface.
This will be the primary interface through which your patrons will search the catalog, place holds, and manage their accounts