Standard Self-Service Launch Checklist

This checklist is the fastest way to go from subscription to a working Koha environment in your own AWS account.

It is written for libraries using the KohaSupport Standard Self-Service path through AWS Marketplace.

Why this matters

The full deployment and setup documentation already exists, but it is spread across multiple guides. This page brings the core launch path into one place so your library can move through the process in the right order.

Before you start

Make sure you have:

• an AWS account
• a payment method on the AWS account
• a decision to use Standard Self-Service rather than Free Tier
• a rough idea of region, instance size, and launch timing
• a decision on whether you need a custom domain right away or later

If your library is new to AWS, read New to AWS? How Koha on AWS works for libraries first.

Step 1: Subscribe in AWS Marketplace

1. Open the KohaSupport Standard Self-Service offering in AWS Marketplace.
2. Subscribe to the product.
3. Choose CloudFormation Template as the delivery method.
4. Continue to launch.

Step 2: Prepare your launch choices

The Standard template will ask for values such as:

• ImageId
• InstanceType
• EBSVolumeSize
• optional VpcId and SubnetId
• optional KeyPairName
• optional EIPAllocationId if you are using an existing Elastic IP
• optional domain and SSL parameters
• S3 backup settings
• optional install languages

Practical recommendations

Instance type

Start with the default recommended Standard instance unless you already know you need something larger.

Storage

20 GiB is the minimum for the data volume. The data volume is a separate EBS volume that holds your MySQL database, Koha configuration, and Koha library files. The root OS disk is a fixed 20 GB managed by the template. Set EBSVolumeSize to at least 50 GiB for a real library.

The data volume persists across AMI upgrades — replacing the AMI does not replace or erase the data volume.

Network

Leave VPC and subnet blank unless you already know you need a specific VPC or subnet.

Key pair

Leave blank if you plan to use AWS-native access methods later. Provide a key pair only if your team specifically wants traditional SSH.

Step 3: Decide how to handle domains and SSL

Simplest path

For the first launch, use the simplest path:

• leave domain-based hosting disabled if you are not ready
• or enable the domain settings without trying to force SSL before DNS is ready

Important Standard behavior

Standard uses an Elastic IP and expects A records for custom domains.

If you enable SSL too early and DNS is not already resolving correctly, SSL setup can fail.

The safer approach is:

1. launch the stack
2. create the DNS A records for your OPAC and Staff subdomains pointing to the Elastic IP
3. wait for propagation
4. then enable SSL later on the instance with the koha-setup-domains command

Do not use a CloudFormation stack update as the casual way to turn SSL on later.

Step 4: Review backup settings

If S3 backups are enabled, the template can create:

• an encrypted S3 backup bucket
• a backup schedule
• retention settings

Choose:

• a schedule that fits your library’s risk tolerance
• a retention period that matches your recovery expectations

Step 5: Launch the CloudFormation stack

Create the stack and wait for it to finish.

Standard deployments are usually measured in minutes rather than days, but exact timing depends on the AWS region and services involved.

Step 6: Record the important outputs

After the stack completes, record these outputs:

• KohaServerIPAddress
• KohaAdminInterfaceURL
• KohaPublicCatalogURL
• KohaAdminCredentialsPath
• DataVolumeId — the EBS volume holding all your library data. Keep a permanent note of this.
• DataVolumeAvailabilityZone — all future instances must use this AZ
• BackupBucketName if S3 backup is enabled
• KohaAutomationRoleArn — paste this as AutomationAssumeRole when running any Koha-Configure-* SSM Automation document
• KohaSSMCommandDocName — paste this as InternalCommandDocumentName when running Automation docs
• ThemeBuilderActivation — activation instructions; check this if you left ActivatePlugin=false at launch

Step 7: Retrieve the administrator credentials

Standard stores the Koha admin credentials in AWS Systems Manager Parameter Store.

Use the output path shown in KohaAdminCredentialsPath.

You can also retrieve the password directly from the instance with:

sudo koha-passwd library

Step 8: Log in and complete post-installation setup

1. Open the staff interface URL from the outputs.
2. Sign in with the credentials you retrieved.
3. Complete the Koha web installer and post-installation setup.
4. Configure your branch, patron categories, item types, and other basics.

Use the existing post-installation setup guide for the deeper setup work.

Step 8a: Activate Koha Theme Builder™

If you set ActivatePlugin=true at launch, Theme Builder activated automatically — verify in Administration → Plugins and proceed to Step 9.

If ActivatePlugin was left as false, activate it now (after completing the web installer above):

Option 1 — SSM Automation (no SSH required)

1. Go to AWS Systems Manager → Automation
2. Run Koha-Configure-ThemeBuilder-{YourStackName} (Documents → Owned by me)
3. AutomationAssumeRole = KohaAutomationRoleArn from Step 6 outputs
4. InternalCommandDocumentName = KohaSSMCommandDocName from Step 6 outputs
5. ApplyNow = true

Option 2 — CLI via Session Manager

sudo /opt/kohasupport/bin/ks-plugin-install library

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

Step 9: Configure your domain and SSL, if needed

If your library wants professional URLs:

1. Create DNS A records for the OPAC and Staff subdomains pointing to the Elastic IP
2. Wait for DNS propagation
3. Enable domains and SSL using one of:

Option A — SSM Automation (no SSH required)

• Run Koha-Configure-Domains-{StackName} from Systems Manager → Automation (with KohaAutomationRoleArn and KohaSSMCommandDocName from Outputs)
• Then run Koha-Configure-SSL-{StackName} when DNS is confirmed propagated

Option B — CLI

• Connect to the instance and run the koha-setup-domains command

Do not enable SSL before DNS is resolving — certificate issuance will fail.

Step 10: Verify backups, access, and basic workflows

Before treating the system as ready:

• verify staff access
• verify OPAC access
• verify backup status if enabled
• verify email, if configured
• test one or two real workflows such as cataloging, patron creation, and circulation

Step 11: Set billing and monitoring basics

Before go-live, make sure your library also sets:

• AWS billing alerts
• basic CloudWatch or operational monitoring expectations
• backup expectations and restore ownership
• an internal plan for who checks the system after launch

Step 12: Understand AMI upgrades and the data volume

The Standard template separates library data from the EC2 instance using a persistent EBS data volume.

What this means in practice:

• Your MySQL database, Koha configuration, and Koha library files all live on the data volume, not on the instance root disk.
• When an AMI is updated, CloudFormation replaces the EC2 instance. The new instance automatically reattaches the same data volume and picks up where the previous instance left off.
• Deleting the CloudFormation stack does not delete the data volume. The volume has a Retain policy and will remain in your account until you manually delete it.

To upgrade to a newer Koha AMI version:

1. Open your CloudFormation stack and click Update.
2. Update the ImageId parameter to the new AMI ID.
3. Apply the change. CloudFormation replaces the instance and the data volume reattaches automatically.
4. Verify the OPAC and staff interface after the update completes.

S3 backups remain your safety net against volume failure or accidental data loss — keep them enabled.

Advanced note: how the data volume works

The Standard AMI uses a persistent EBS data volume separate from the instance root disk. On first boot, the instance initialises the data volume with the MySQL data directory, Koha configuration, and key Koha directories. On subsequent boots (including after an AMI upgrade), the instance detects that the volume is already initialised and simply reattaches and mounts it without touching the data.

This design means AMI upgrades are safe and do not require a backup-and-restore cycle. Configuration is pulled from AWS Systems Manager Parameter Store by the bootstrap process.

Related guides

• New to AWS? How Koha on AWS works for libraries
• Which Koha on AWS option is right for your library?
• How to choose the right Koha on AWS setup
• Who handles what? Self-Service, Managed Services, and AWS responsibilities
• Post-Installation Setup Guide

Need help?

If your library wants help with migration, setup, training, or launch planning, talk to KohaSupport.