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

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. Under Parameters, leave most values at their defaults.
3. KohaSupport Marketplace AMI ID should be pre-filled from your subscription.
4. InstanceType:
   Leave blank to use the default:
   • t3.medium for x86_64
   • t4g.medium for ARM64

   You may override with any valid EC2 instance type.

5. EnableSSH: Set to true to enable SSH access (recommended).
6. SSHAccessCIDR:
   Enter your IP with /32 (e.g., 203.0.113.55/32).
   Leave blank to use the default: 10.0.0.0/16.
   Avoid using 0.0.0.0/0 unless temporarily needed for troubleshooting or password recovery.
7. VpcId / SubnetId:
   Leave blank to create a new VPC and subnet automatically.
   To use your own:
   • Enter a valid VPC ID and a matching Subnet ID.
   • Find these values in the AWS VPC dashboard.
8. 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:

• KohaStaffURL: URL to access the Koha staff/admin interface (port 8080). Use this to complete the post-installation setup.
• KohaOPACURL: URL to access the public OPAC (catalog) interface (port 80).
• PublicIP: The static public IP assigned to your Koha server.
• SSHCommand: SSH connection string to access the server. Required for maintenance or password recovery.
• KohaCredentialsSSMPath: The path in AWS Systems Manager Parameter Store where the Koha admin password is stored. This is used for retrieving the admin password securely.

If you enabled SSH access, secure it by doing the following:

Option 1: Update the Security Group

• Go to EC2 > Security Groups
• Locate the group named “KohaServer”
• Edit inbound rules and restrict access to your IP

Option 2: Update via CloudFormation

• Go to CloudFormation > Select your stack > Update
• Use current template and change SSHAccessCIDR
• Re-deploy the stack

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 (KohaCredentialsSSMPath).
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 SSH:

1. Connect to your EC2 instance:
   • Use the SSH command provided in the CloudFormation Outputs or connect via EC2 Instance Connect.
   • Example SSH 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.
2. Via EC2 Instance Connect:
   • If SSH access was enabled, go to the AWS EC2 console.
   • Select your instance and click “Connect” > “EC2 Instance Connect”.
   • Enter the username ubuntu and click “Connect”.
3. 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 (KohaStaffURL).

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 (KohaCredentialsSSMPath).
• 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 (KohaCredentialsSSMPath).
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.
• 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