Domain names are taken for granted. It's one of those things that are assumed to be there and if they're not - calamity ensues.
We see tons of tutorials out there showing how to create an API or build a website, but rarely do we see how to add that one piece of necessary polish - a domain name.
So today we're going to tie the bow on our WebSocket tutorial by adding a custom domain.
This is part 5 of an introductory series to WebSockets. Each part builds on the one before, so if you're joining us now, I'd highly recommend reading the first four parts.
- Part One - Building a WebSocket
- Part Two - Securing your WebSocket
- Part Three - Documentation Using Async API Spec
- Part Four - User Notifications
Prerequisites
There are two things you must do before configuring a custom domain: purchase your domain name and setup a public hosted zone. These will need to be done manually in order to pick up and deploy the stack contained in part five of the GitHub repo for the WebSocket.
Purchasing the domain name must be done manually. The hosted zone technically could be done through our SAM template, but it was built with the assumption that you also have a REST or HTTP API under the same domain name. With that assumption, we would be reusing the public hosted zone in Route53.
If you want to get started putting one of your existing REST or HTTP APIs behind a custom domain, I wrote this post walking you through how to do it in the AWS console.
New Parameters
If you've been following along in the series and have been using the samconfig.toml
file generated from the sam deploy --guided
command, you need to run the command again. If you are joining us now for the first time, you need to run the command for the first time to configure the deployment parameters.
There are three new parameters for deploying the custom domain:
-
DeployCustomDomain - Set to
true
if you want to deploy a custom domain. If you do not wish to do so, set it to false. - DomainName - The domain name you want to your WebSocket to be behind. In my example, I use ws.gopherholesunlimited.com.
-
HostedZoneId - The identifier of the public hosted zone you created
- You can get this value from the AWS console or from the following AWS CLI command: aws route53 list-hosted-zones
-
NOTE - do not include
/hostedzone/
in the id. Only use the string after that.
-
NOTE - do not include
- You can get this value from the AWS console or from the following AWS CLI command: aws route53 list-hosted-zones
Domain Resources
There are several components in play for setting up a domain name in AWS for a WebSocket. None of which are particularly intuitive to piece together.
Component diagram for setting up a WebSocket API behind a custom domain
The resources we are deploying to get our WebSocket to use the custom domain are:
- ACM Certificate - AWS Certificate that verifies we own the domain
- API Gateway v2 Domain Name - Configures a custom domain in API Gateway for a WebSocket
- Domain Mapping From Domain Name to API - Sets the base path (/) to use our WebSocket API with the correct Stage
-
CNAME DNS Record - DNS record that maps the
id
of our domain name to a global record
These are all configured and ready to deploy in the SAM template. Once you configure the deployment parameters and run the deploy
command, our WebSocket will be reachable by our custom domain name!
Important Note - The SAM deployment will work if you have purchased your domain name through Route53. AWS allows for automatic DNS verification if your domain is in Route53, it resides in the AWS account you are deploying to, and you are using DNS validation (which we are).
Picking Your Domain Name
One thing to remember when choosing your domain name is that it cannot share an existing domain with an HTTP or REST API. Domain names must be used with a single type of API only.
This means if you have your REST or HTTP API behind a domain name like api.gopherholesunlimited.com, you cannot use a base path for your websocket (api.gopherholesunlimited.com/websocket). It must be its own completely separate domain in API Gateway.
Based on this, I'd recommend creating a separate subdomain for your WebSocket like I did, ws.gopherholesunlimited.com.
Connecting To Updated WebSocket
With the new domain name in place, the method of connection stays mostly the same. You will still need to connect to your domain via the wss
protocol and you're still required to add the access_token
header. My WebSocket connection url would be:
wss://ws.gopherholesunlimited.com?access_token=eyJ******
Updating our connection url in Postman and trying to connect....
Successfully connected via our custom domain!
Conclusion
This wraps up our series on WebSockets. There is one more post coming on how to implement WebSockets into your application to go from long running synchronous endpoints to fluid, async workflows with status updates.
I hope you have enjoyed learning about WebSockets and have had as much fun as I've had writing all this. It was an adventure. I hope you are able to get the stack deployed, try it out, and even integrate it into your application!
Happy coding!
Top comments (0)