This guide explains how to deploy, secure, monitor, and manage the Koha ILS using the AWS CloudFormation template.

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”.

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

1. Leave the default settings as they are.
2. Set Prepare template to Choose an existing template.
3. Set Template source to Amazon S3 URL.
4. The template URL should already be pre-filled with the Koha CloudFormation template.
5. Click Next.

Step 2: Specify stack details

1. Enter a name for your stack (e.g., KohaLibrarySystem).
2. ImageID: This will be pre-filled from your marketplace subscription.
3. InstanceType: You can specify any valid EC2 instance type. Leave blank to use the default:
   • t3a.medium for x86_64
   • t4g.medium for ARM64
4. 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.
5. 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. 
   
6. VpcId / SubnetId:  Optional. Leave blank to use the default VPC, otherwise you can specify a valid VPC ID and subnet.
7. Click Next.

Step 3: Configure stack options

1. Leave default options or add tags for identification and cost tracking.
2. Check the box to acknowledge IAM resource creation.
3. Click Next.

Step 4: Review

1. Verify all stack details and parameter values.
2. Click Submit to deploy the CloudFormation stack.

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’.

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.

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):

1. Go to the AWS Systems Manager console.
2. Navigate to Parameter Store.
3. Search for the parameter using the path shown in the CloudFormation Outputs (KohaAdminCredentialsPath).
4. Click on the parameter to view its details.
5. Click “Show value” to reveal the Koha admin password.
6. 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.

Via EC2 Instance Connect:

1. • • Go to the AWS EC2 console.
     • Select your instance and click “Connect” > “EC2 Instance Connect”.
     • Enter the username ubuntu and click “Connect”.
2. 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.

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:

1. Go to AWS Key Management Service (KMS) > Customer managed keys.
2. Select the key used for EBS (default is AWS-managed).
3. Use the “Rotate key” option or create a new key.
4. Re-encrypt the volume using the new key (requires snapshot and restore).

SSM Parameter Encryption Key Rotation:

1. Go to AWS KMS > Customer managed keys.
2. Rotate the key or create a new one.
3. Update the SSM parameter to use the new key (only needed if using a customer-managed key).

Koha Admin Password Rotation:

1. Reboot the instance to automatically rotate the password (new password is stored in SSM),
   OR
2. 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:

1. Go to AWS Systems Manager > Parameter Store.
2. Search for the parameter using the path from the CloudFormation Outputs (KohaAdminCredentialsPath).
3. 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

• 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/

Purpose for AWS IAM Roles and Policies

• EC2 Instance Role:
  • Allows the instance to perform actions such as:
  • ssm:PutParameter – Write SSM parameters
  • ec2: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 – OPAC
  • 8080 – Staff Interface
  • 22 – SSH (optional, restricted by SSHAccessCIDR)
• 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

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 and t2.micro instances. See https://aws.amazon.com/free/ for details.
  • 30 GB EBS storage/month. See https://aws.amazon.com/ebs/pricing/ for details.
• 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.

• Daily Backups:
  • Saved to /var/spool/koha/library/ on the instance.
  • Can be copied via SSH or downloaded from the Koha staff interface.
• Restore:
  1. Launch a new instance.
  2. Upload backup file.
  3. Restore using Koha command-line tools:
     sudo koha-restore sqldump configdump

• 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.

• 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 and 8080.
  • 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
• 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.
• 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/*
• 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/

This will be the primary interface through which your patrons will search the catalog, place holds, and manage their accounts