Overview

Koha AMIs deployed through the AWS Marketplace support automatic SSL/TLS certificates using Let’s Encrypt. SSL provides secure HTTPS access for both your OPAC and staff interfaces.

This guide explains two options:

• Method A: Enable SSL during the initial CloudFormation launch.
• Method B: Enable SSL manually after deployment using the Koha CLI tool.

SSL requires correctly configured DNS. Both your OPAC and staff domains must resolve to the server’s Elastic IP (EIP) before the certificate process can succeed.

---

Method A: Enable SSL During CloudFormation Launch

This method triggers SSL configuration automatically during the initial Koha deployment.

A1. DNS Must Be Ready Before EC2 Initialization

During launch, the CloudFormation stack creates your EC2 instance. As soon as the instance boots, it attempts to request SSL certificates using Let’s Encrypt.

Important: Your DNS A records must already point to the Elastic IP before the instance starts its initialization scripts. Otherwise SSL will fail and require manual setup.

A2. Find the Elastic IP (EIP)

You must create DNS A records to make your domain resolve to Koha’s server.

1. Open the CloudFormation stack created during Marketplace launch
2. Go to the Resources tab
3. Locate the resource of type AWS::EC2::EIP
4. Copy the value under “Physical ID” — this is your server’s IP address

A3. Create DNS A Records

Create two A records in your DNS provider using the EIP:

Hostname	Example	Target
OPAC site	library.yourdomain.com	Elastic IP
Staff site	libadmin.yourdomain.com	Elastic IP

Cloudflare Example

1. Open your domain in Cloudflare
2. Go to the DNS tab
3. Click Add record
4. Type: A
5. Name: library or libadmin
6. Paste the Elastic IP
7. Set Proxy Status to DNS only
8. Save

Once DNS resolves, the EC2 instance will complete SSL setup automatically using Let’s Encrypt.

A4. Confirm SSL Deployment

When deployment completes, visit:

• https://library.yourdomain.com
• https://libadmin.yourdomain.com

If the DNS was not ready in time, SSL may fail. In that case, use Method B to enable SSL manually.

---

Method B: Enable SSL After Deployment (CLI Tool)

Use this method if:

• Your DNS A records were created too late during the CloudFormation deployment
• You need to update your domain or reissue certificates
• You prefer manual control over SSL configuration

B1. Access the EC2 Instance via EC2 Instance Connect

1. Open AWS Console → EC2
2. Select Instances
3. Choose your Koha instance
4. Click Connect
5. Choose the EC2 Instance Connect tab
6. Click Connect

You will now have terminal access in your browser.

B2. Run the SSL Setup Command

After confirming that your DNS A records resolve to the Elastic IP, run:

koha-setup-domains --domain yourdomain.com \ --opac-subdomain library \ --staff-subdomain libadmin \ --enable-ssl \ --ssl-email [email protected] 

This command performs the full SSL setup:

• Prepares Apache for HTTPS
• Requests certificates from Let’s Encrypt
• Installs the certificates
• Reloads Apache

B3. Optional: Use Let’s Encrypt Staging Server

Useful if you want to test without hitting rate limits:

koha-setup-domains --domain yourdomain.com \ --enable-ssl \ --ssl-email [email protected] \ --certbot-staging 

B4. Re-run or Force Non-Interactive Mode

If you need to reissue certificates:

koha-setup-domains --domain yourdomain.com --enable-ssl --yes 

---

Verify SSL

Check your live URLs:

• https://library.yourdomain.com
• https://libadmin.yourdomain.com

Use command-line testing as well:

curl -I https://library.yourdomain.com 

---

Troubleshooting

• Let’s Encrypt validation fails:
  A records do not point to the Elastic IP, or DNS has not propagated.
• SSL works for OPAC but not staff (or vice versa):
  Check both A records individually.
• Rate limit errors:
  Use the staging flag:

  --certbot-staging

• Apache still serves HTTP:
  Re-run domain setup:

  koha-setup-domains --domain yourdomain.com --enable-ssl

• DNS behind Cloudflare proxy (orange cloud):
  Set records to “DNS only,” otherwise Let’s Encrypt cannot validate.