Custom Domain

Jets can create and associate a route53 custom domain with the API Gateway endpoint. Jets manages the vanity route53 endpoint that points to the API Gateway endpoint. It adjusts the endpoint transparently without you having to update your endpoint if Jets determines that a new API Gateway Rest API needs to be created. The route53 record is also updated. Here’s a table with some example values to explain:

Vanity Endpoint API Gateway Endpoint Jets env
dev-demo.coolapp.com a02oy4fs56.execute-api.us-west-2.amazonaws.com (not set)
dev-demo-2.coolapp.com xyzoabc123.execute-api.us-west-2.amazonaws.com 2

Here’s a diagram also:

Vanity Endpoint

To create a vanity endpoint edit the config/application.rb and edit domain.certificate_arn and domain.hosted_zone_name:

Jets.application.configure do
  config.domain.certificate_arn = "arn:aws:acm:us-west-2:112233445577:certificate/8d8919ce-a710-4050-976b-b33da991e7e8" # String
  config.domain.hosted_zone_name = "coolapp.com" # String
  # config.domain.name = "#{Jets.project_namespace}.coolapp.com" # Default is nil

  # NOTE: Changing the endpoint_configuration results in 10 minutes of downtime
  config.domain.endpoint_configuration = { types: ["REGIONAL"] } # EDGE or REGIONAL
  config.domain.regional_certificate_arn = "..." # String
end

You can create an AWS Certificate with ACM by following the docs: Request a Public Certificate. The hosted zone name on Route53 is required. Here are the docs to create one: Creating a Public Hosted Zone.

Controlling Domain Name

By default, the domain name is a subdomain with Jets.project_namespace as the value. Example:

#{Jets.project_namespace}.coolapp.com = demo-dev.coolapp.com

When JETS_ENV_EXTRA=1 is set the values looks like this:

#{Jets.project_namespace}.coolapp.com = demo-dev-1.coolapp.com

You can set the domain name yourself and override the default behavior like so:

Jets.application.configure do
  config.domain.name = "mysubdomain.coolapp.com"
end

Changing Endpoint Configuration Warning

When routes change, Jets detects this and fully re-creates the Rest API Gateway. If you change the API Gateway domain endpoint_type REGIONAL to EDGE and vice versa, this results in downtime as the CloudFormation updates the endpoint type in-place.

  • Going from REGIONAL to EDGE results in about 10 minutes of unavailability. That’s about how long it takes API Gateway to create the CloudFront Edge endpoint.
  • Going from EDGE to REGIONAL results in about 30 seconds of unavailability. That’s about how long it takes API Gateway to create the Regional endpoint.

If you need to switch this and avoid downtime, you will need to do a manual blue-green deployment by creating a new environment with JETS_ENV_EXTRA.

Pro tip: Use the <- and -> arrow keys to move back and forward.

Edit this page

See a typo or an error? You can improve this page. This website is available on GitHub and contributions are encouraged and welcomed. We love pull requests from you!