Stacktape
Stacktape

Domains and TLS Certificates



This page explains how to manage custom domains and TLS certificates in Stacktape.

If you don't have a domain, you can register one. If you already have a domain, you have two options:

  1. Use AWS Route 53 as your DNS provider (recommended): If you use Route 53, Stacktape can automatically manage your domain, generate and renew TLS certificates, and create DNS records for your resources. See Managing domains with Stacktape. If you currently use a third-party DNS provider, you can migrate your domain to Route 53.
  2. Use a third-party DNS provider: If you use a provider like Cloudflare or GoDaddy, you must manage your DNS records manually. You will also need to create or import a custom TLS certificate in the AWS Certificate Manager console and reference it in your Stacktape configuration. See Using a third-party DNS.

Managing domains with Stacktape

If you use Route 53 as your DNS provider, you can use the stacktape domain:add command to prepare your domain for use with Stacktape. This command will guide you through creating TLS certificates and, optionally, configuring AWS SES for your domain.

You only need to run this command once per region for each domain.

stacktape domain:add --region <<region>>

After the command completes successfully, you can use your domain and its subdomains in your Stacktape configuration. Stacktape will automatically create the necessary DNS records and assign the correct certificates during deployment.

resources:
  apiService:
    type: web-service
    properties:
      # ...
      customDomains:
        - domainName: api.mydomain.com


  web:
    type: hosting-bucket
    properties:
      # ...
      customDomains:
        - domainName: mydomain.com

Migrating an existing domain

If you have a domain that is currently managed by a third-party DNS provider, you can migrate it to Route 53 to let Stacktape manage it. The stacktape domain:add command can help you with this process.

If your domain is actively in use, you should follow the AWS tutorial on migrating DNS for an active website to avoid downtime.

Run the stacktape domain:add command and confirm that you want to create a hosted zone. The command will then provide you with a list of name servers.

To complete the migration:

  1. Copy your existing DNS records from your current DNS provider to the new hosted zone in the AWS Route 53 console.
  2. Update the name server (NS) records at your domain registrar to point to the name servers provided by the stacktape domain:add command.

It can take up to 48 hours for the name server changes to propagate.

After the migration is complete, run stacktape domain:add again to finish the setup process.

Assigning custom domains to resources

To assign a domain to a supported resource, use the customDomains property. During deployment, Stacktape will create the necessary DNS records.

To learn more, see the documentation for these resources:

Using subdomains

You can use subdomains with your resources, and you can use variables to create dynamic subdomain names based on the stage.

resources:
  myHttpApi:
    type: 'http-api-gateway'
    properties:
      customDomains:
        - domainName: $Format('{}.mydomain.com', $Stage())

Registering a domain

You can register a new domain in the AWS Route 53 console. Once your domain is registered, you can follow the steps in Managing domains with Stacktape.

Using a 3rd-party DNS

If you manage your DNS records with a third-party provider, you must create or import a custom TLS certificate in the AWS Certificate Manager console.

You can then reference the certificate's ARN in your Stacktape configuration. Remember to disable DNS record creation, as Stacktape does not have control over your DNS records in this setup.

resources:
  apiService:
    type: web-service
    properties:
      # ...
      customDomains:
        - domainName: mydomain.com
          disableDnsRecordCreation: true
          customCertificateArn: <<ARN_OF_YOUR_CERTIFICATE>>

After deploying, you will need to create a CNAME or ALIAS record in your DNS provider's dashboard that points to the domain of the created resource. You can find the resource's domain in the Stacktape Console.

Contents