Custom Domain

Deploy Talkr AI with your own custom domain name for a professional production setup. By now, you should be able to create and test a voice agent by following the previous guide to setup the platform on a remote server using Docker

What is Custom Domain Deployment?

Custom domain deployment allows you to run Talkr AI with a personalized domain name (like voice.yourcompany.com) instead of using IP addresses. This setup includes:

• Custom Domain: Access your application via a memorable domain name
• Automatic SSL: Proper SSL certificates from Let's Encrypt or similar providers
• Professional Setup: Production-ready configuration for business use
• Easy Sharing: Share a clean URL with your team and customers

Prerequisites

Before starting, ensure you have:

• A domain name you own (e.g., yourcompany.com)
• Access to your domain's DNS settings (usually through your domain registrar)
• Talkr AI already running on your server via the remote deployment guide
• Your server's public IP address

Step 1: Configure DNS Records

You need to create a DNS record that points your domain to your server's IP address.

Add an A Record

Log in to your domain registrar or DNS provider and add an A record:

Verify DNS Propagation

Before proceeding, verify that your domain points to your server:

nslookup voice.yourcompany.com

You should see your server's IP address in the response.

Step 2: Quick Setup (Recommended)

Once your DNS is configured, run the automated setup script that handles the rest.

cd talkr
chmod +x scripts/setup_custom_domain.sh && sudo ./scripts/setup_custom_domain.sh

The script will prompt you for:

• Your domain name
• An email address for Let's Encrypt notifications

It will automatically:

• Verify DNS configuration
• Install Certbot
• Generate Let's Encrypt SSL certificates
• Update the canonical public host/base URL settings in .env
• Validate the runtime config that talkr-init will render from .env
• Configure automatic certificate renewal
• Restart Talkr services through the validated startup wrapper

Once complete, your application will be available at https://voice.yourcompany.com.

Manual Setup

If you prefer to configure everything manually, follow these steps instead of using the automated script.

Install Certbot

Certbot is the official Let's Encrypt client that automates SSL certificate generation.

Ubuntu/Debian:

sudo apt update
sudo apt install certbot -y

Amazon Linux/RHEL:

sudo yum install certbot -y

Point .env at your domain

Update .env so the canonical remote settings use your domain — talkr-init reads these to render nginx's server_name. Replace voice.yourcompany.com with your actual domain throughout:

cd talkr
sed -i "s/^PUBLIC_HOST=.*/PUBLIC_HOST=voice.yourcompany.com/" .env
sed -i "s|^PUBLIC_BASE_URL=.*|PUBLIC_BASE_URL=https://voice.yourcompany.com|" .env

Start services so nginx can answer the ACME challenge

Bring the stack up (or recreate it) through the validated wrapper. nginx serves the Let's Encrypt HTTP-01 challenge from certs/.well-known/acme-challenge/ on port 80, so the stack must be running during issuance — there's no need to stop it:

./remote_up.sh

Generate the SSL certificate (webroot)

Issue the certificate using the webroot challenge served by the running nginx:

sudo certbot certonly --webroot -w "$(pwd)/certs" -d voice.yourcompany.com

Certbot will:

1. Write a challenge file under certs/.well-known/acme-challenge/
2. Have Let's Encrypt fetch it over HTTP (port 80) to verify you control the domain
3. Store the certificate in /etc/letsencrypt/live/voice.yourcompany.com/

Copy the certificate and load it

Copy the issued certificate into the certs/ directory nginx reads, then restart nginx to load it:

sudo cp /etc/letsencrypt/live/voice.yourcompany.com/fullchain.pem certs/local.crt
sudo cp /etc/letsencrypt/live/voice.yourcompany.com/privkey.pem certs/local.key
sudo chmod 644 certs/local.crt certs/local.key
sudo docker compose --profile remote restart nginx

Access Your Application

Your application is now available at:

https://voice.yourcompany.com

You should see a valid SSL certificate (green padlock) in your browser.

Set Up Certificate Renewal

Let's Encrypt certificates expire after 90 days. Set up automatic renewal.

Create a renewal hook script that copies the new certificates:

sudo nano /etc/letsencrypt/renewal-hooks/deploy/talkr-reload.sh

Add the following content (replace paths as needed):

#!/bin/bash
# Copy renewed certificates to talkr certs directory
cp /etc/letsencrypt/live/voice.yourcompany.com/fullchain.pem /home/ubuntu/talkr/certs/local.crt
cp /etc/letsencrypt/live/voice.yourcompany.com/privkey.pem /home/ubuntu/talkr/certs/local.key
chmod 644 /home/ubuntu/talkr/certs/local.crt /home/ubuntu/talkr/certs/local.key

# Restart nginx to load new certificates
cd /home/ubuntu/talkr
docker compose --profile remote restart nginx

Make the script executable:

sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/talkr-reload.sh

Test that renewal works:

sudo certbot renew --dry-run

Troubleshooting

Certificate Generation Fails

If Certbot fails to generate certificates:

1. Port 80 blocked: Ensure port 80 is open in your firewall and reachable from the internet. With the webroot flow nginx must be running and serving the challenge on port 80 (don't stop the stack)
2. DNS not propagated: Wait for DNS changes to propagate and verify with nslookup
3. Rate limits: Let's Encrypt has rate limits. If you've exceeded them, wait before retrying

SSL Certificate Errors in Browser

If you see SSL errors after setup:

1. Verify the certificates were copied correctly: ls -la talkr/certs/
2. Run ./remote_up.sh --preflight-only in talkr/ to verify the talkr-init runtime render matches .env
3. Restart the nginx container: sudo docker compose --profile remote restart nginx

WebRTC Connection Issues

If voice calls don't connect after domain setup:

1. Ensure TCP/UDP ports 3478, 5349, and UDP 49152-49200 are still open
2. Check that PUBLIC_HOST / PUBLIC_BASE_URL in .env match your domain, then re-run ./remote_up.sh