Skip to content

Route53 Domain Companion for setting up Email Forwarding and Domain Redirects automatically

License

Notifications You must be signed in to change notification settings

weirdion/domain-companion

Repository files navigation

Domain Companion

Overview

A CDK based project with two main features:

  • Domain redirection
    • provision S3 redirection
    • use CloudFront to add https on top of S3
  • Email alias forwarding
    • use SES to receive incoming mail
    • store it in S3 bucket
    • leverage Lambda to forward the email based on a map stored in SSM

Worthwhile reading for understanding concepts: SES email receiving concepts.

Setup Build

Before starting to build and deploy, please ensure that the domain and emails you are using are verified identities in AWS SES.

The domain-map.json.example file shows an example of the email map configuration.
Copy domain-map.json.example to domain-map.json file with your mapping.

[
    {
        // hosted zone name
        "hostZoneName": "example.com",
        // hosted zone id
        "hostedZoneId": "ABCD1234",
        // 301 https redirection (Cloudfront + Lambda@Edge)
        "redirects": [
          {
              // example.com -> dev.to
              "subDomain": ".",
              "targetDomain": "dev.to",
              "uri": {
                // example.com/test -> dev.to/about
                "test": "dev.to/about"
              }
          },
          {
              // dev.example.com -> dev.to
              "subDomain": "dev",
              "targetDomain": "dev.to"
          }
        ],
        // bounce email of emails below, only required if emails is non-empty
        "bounceEmail": "no-reply@example.com",
        // emails aliases to forward, bounce_email must be set
        "emails": [
            {
                // Email address that will be used as "FROM" to receiving email
                // reply-to email will be the original sender's reply-to email
                "fromSender": "no-reply@example.com",
                // email address to capture as recipient
                // supports plus addressing, a+tag@example, a+tag2@example both would match with a@example.com
                "alias": "a@example.com",
                // email address(es) to deliver this alias to
                "recipients": [
                    "a@myExistingEmail.com",
                    "b@myExistingEmail.com"
                ],
                // prefix to add to the subject line, usually for visually categorizing types of emails for this alias
                // can be empty string or any arbitrary string of less than 13 characters
                // a space is added while joining existing subject and prefix
                "subjectPrefix": "[Category1]"
            }
        ]
    }
]

The cdk.json file tells the CDK Toolkit how to execute your app.

Build and Deploy

Before getting ready to deploy, ensure the dependencies are installed by executing the following:

$ npm install -g aws-cdk
$ npm install

Useful commands

  • npm run build compile typescript to js
  • npm run watch watch for changes and compile
  • npm run test perform the jest unit tests
  • cdk deploy deploy this stack to your default AWS account/region
  • cdk diff compare deployed stack with current state
  • cdk synth emits the synthesized CloudFormation template

About

Route53 Domain Companion for setting up Email Forwarding and Domain Redirects automatically

Topics

Resources

License

Stars

Watchers

Forks