Overview

Our custom Koha Amazon Machine Images (AMIs), available through the AWS Marketplace, allow you to use your own custom domain (for example, library.yourdomain.com) for both the OPAC and staff interfaces. Using a personal domain makes your library system more professional, easier to remember, and easier for patrons to access.

This guide provides two options:

• Method A: Configure the domain during the initial AWS Marketplace launch using the CloudFormation template.
• Method B: Configure or change the domain later using the Koha command-line tool.

Both methods require DNS (Domain Name System) configuration. DNS maps human-readable names (like library.yourdomain.com) to your server’s IP address using A records.

1. Before You Begin

You will need:

• A registered domain name (Cloudflare, Namecheap, Route 53, GoDaddy, etc.)
• Access to your DNS provider’s dashboard
• A Koha AMI deployment launched through the AWS Marketplace
• The relevant CloudFormation parameters, depending on the method you choose

Method A: Custom Domain Setup During Launch (CloudFormation Template)

This method configures your custom domain while you launch Koha using the AWS Marketplace “Launch with CloudFormation” option.

A1. Locate Your CloudFormation Stack

When you subscribe and launch Koha from the AWS Marketplace, AWS automatically creates a CloudFormation stack.

1. Log in to the AWS Console
2. Open CloudFormation
3. Look under Stacks for a stack name beginning with Koha-AMI- or the name you entered during setup

A2. Find the Elastic IP (EIP)

The EIP is required to configure DNS.

1. Open your CloudFormation stack
2. Click the Resources tab
3. Search for a resource of type AWS::EC2::EIP
4. The “Physical ID” value is your server’s public IP

A3. Create DNS A Records

In your DNS provider, create two A records pointing to the Elastic IP.

Cloudflare Example

1. Open your domain in Cloudflare
2. Go to DNS
3. Click Add record
4. Type: A
5. Name: library (OPAC) or libadmin (staff)
6. Paste the Elastic IP into “IPv4 address”
7. Set Proxy Status to DNS only
8. Save

Cloudflare usually updates within seconds.

A4. Continue Deployment

After your DNS A records are pointing to the Elastic IP, CloudFormation will complete the setup. Your OPAC and staff domains should start loading over HTTP.

Method B: Custom Domain Setup After Deployment (CLI Tool)

Use this method if:

• Your DNS was not ready during the initial deployment
• You want to change your domain later
• You prefer manual configuration

B1. Access the EC2 Instance via EC2 Instance Connect

This requires no SSH key.

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

You will see a command-line terminal in your browser.

B2. Run the Domain Setup Command

Use this command to configure or reconfigure your custom domain:

koha-setup-domains --domain yourdomain.com \ --opac-subdomain library \ --staff-subdomain libadmin 

This updates the Apache virtual host configuration immediately. You can run it multiple times if you change DNS records or need corrections.

7. Verify Domain Resolution

Use these commands to confirm that each domain correctly points to the server:

dig library.yourdomain.com nslookup libadmin.yourdomain.com curl -I http://library.yourdomain.com 

Each result should show the Elastic IP assigned to your Koha server.

8. Troubleshooting

• Wrong page or default Apache page appears:
  Ensure your DNS record type is A, not CNAME.
  Re-run the tool:

   

  koha-setup-domains --domain yourdomain.com

• Nothing loads:
  Check whether the Elastic IP has changed or been released.
• DNS not propagating:
  Check the TTL on your DNS provider.