Skip to content

Latest commit

 

History

History
233 lines (171 loc) · 8.1 KB

installation.md

File metadata and controls

233 lines (171 loc) · 8.1 KB
Raw

Installation Guide

Before start, please make sure you understand the potential cost and the limitations.

If you need support, feel free to contact me.

1. Preparation

1.1 Decide on one AWS region

As mentioned in the limitations section, there are only 3 regions that support email receiving at the moment.

  1. us-east-1 US East (N. Virginia)
  2. us-west-2 US West (Oregon)
  3. eu-west-1 Europe (Ireland)

Please choose one based on your preference. You will need the corresponding region code whenever you see [YOUR REGION HERE]

1.2 Setup aws-cli v2

By following the instructions on AWS, you will need to create a user on AWS IAM with AdministratorAccess (or permissions that covers all aws-cli usage below) and configure the credential using the following command:

aws configure

# AWS Access Key ID [None]: .....
# AWS Secret Access Key [None]: .....
# Default region name [None]: .....
# Default output format [None]: .....

1.3 Setup Github CLI

Similar to the previous step, just follow the instructions on Github. Be sure to authenticate yourself by:

# start interactive setup
gh auth login

2. Setting it up

2.1 Fork

To begin, please fork the repository and clone it locally.

# Fork and clone it at the same time
gh repo fork edmundhung/maildog --clone
# Or if you would like to create a fork in an organization
# gh repo fork edmundhung/maildog --clone --org name-of-organization
# From now on, all commands provided assumes the root of the project being your working directory
cd maildog
# Ensure all `gh` command works against your fork instead of the original repository
export GH_REPO=[YOUR USER/ORGANIZATION NAME]/maildog;
# Create production branch from main branch [default branch]
# All your changes below should be pushed to the production branch
# The deploy workflow will automatically deploy changes pushed to this branch
git checkout -b production

2.2 Configure maildog with maildog.config.json

A JSON file with the name maildog.config.json is required at the root of the project. The format as follows:

// This config file support json with comment (jsonc)
// It simply adds support to single line (//) and multi-line comments (/* ... */) on `json` document
{
  "domains": {
    "exmaple.com": {                    // your domain here
      "fromEmail": "foo",               // optional, default: "noreply"
      "scanEnabled": false,             // optional, default: true,
      "tlsEnforced": false,             // optional, default: false,
      "fallbackEmails": [],             // optional, default: []
      "alias": {                        // required if `fallbackEmails` are not set
        "bar": {                        // result in `[email protected]`
          "description": "Lorem ipsum", // optional, default: ""
          "to": ["[email protected]"]     // required
        }
      }
    }
  }
}
  • fromEmail: The sender email address used when maildog forward the email
  • scanEnabled: If true, then emails received will be scanned for spam and viruses
  • tlsEnforced: Specifies whether maildog should require that incoming email is delivered over a connection encrypted with Transport Layer Security (TLS).
  • fallbackEmails: A catch-all / wildcard rule. All emails received on the corresponding domain will be forwarded to these email addresses unless specified in the alias section.
  • alias: The email prefix with a description and list of email addresses forwarding to

Here is an example config.

2.3. Verify your domain and email address on AWS SES

In this step, you might prefer verifying your domain through the AWS console UI as it will guide you through the DNS records that need to be created. But if you are familiar with a DNS zone file, you can generate one using the command below:

DOMAIN=[YOUR DOMAIN HERE];
REGION=[YOUR REGION HERE];
sed \
-e "s|\${Domain}|$DOMAIN|g" \
-e "s|\${Region}|$REGION|g" \
-e "s|\${VerificationToken}|$(aws ses verify-domain-identity --domain "$DOMAIN" --output text)|g" \
-e "s|\${DkimToken\[0\]}|$(aws ses verify-domain-dkim --domain "$DOMAIN" --query DkimTokens[0] --output text)|g" \
-e "s|\${DkimToken\[1\]}|$(aws ses verify-domain-dkim --domain "$DOMAIN" --query DkimTokens[1] --output text)|g" \
-e "s|\${DkimToken\[2\]}|$(aws ses verify-domain-dkim --domain "$DOMAIN" --query DkimTokens[2] --output text)|g" \
./examples/maildog.zonefile.txt

If you are new to AWS SES and you are setting up with the sandbox. You MUST verify the email address that you are forwarding to with AWS using the following command:

aws ses verify-email-identity --email-address [YOUR EMAIL HERE]

2.4 Setup secrets

To let Github managing maildog for you, there are 4 secrets that need to be set.

2.4.1 AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY

To deploy maildog, we need to set up an IAM user with Programmatic access. We have prepared an example JSON policy for your reference. You can also create the user and set the corresponding secrets using the command below:

# Create IAM User - `maildog-user`
aws iam create-user --user-name maildog-user
# Create IAM Policy - `maildog-policy`
aws iam create-policy --policy-name maildog-policy --policy-document file://docs/maildog-policy.json
# Attach policy `maildog-policy` to user `maildog-user`
aws iam attach-user-policy --user-name maildog-user --policy-arn $(aws iam list-policies --query "Policies[?PolicyName=='maildog-policy'].Arn" --output text)
# Generate Sign-in credentials for user user `maildog-user`
# Set AccessKeyId and SecretAccessKey as secret
aws iam create-access-key --user-name maildog-user --query "AccessKey.[AccessKeyId,SecretAccessKey]" --output text \
| tee >(awk '{print $1;}' | gh secret set AWS_ACCESS_KEY_ID) >(awk '{print $2;}' | gh secret set AWS_SECRET_ACCESS_KEY)

2.4.2 AWS_REGION

You must also provide the region code as a secret for Github to deploy maildog to your preferred region:

# Set AWS region as secret
gh secret set AWS_REGION -b"[YOUR REGION HERE]"

2.4.3 ENCRYPT_PASSPHRASE

In order to protect your config detail from the public, it should be encrypted before commit:

# Encrypt maildog.config.json with gpg
# You will be asked to enter a passphrase twice
# A file with the name  `maildog.config.json.gpg` will be created
npm run encrypt-config
# Commit the encrypted config
git add maildog.config.json.gpg && \
git commit -m "build: configure maildog"
# Set the passpharse as secret so the workflows can decrypt the config
gh secret set ENCRYPT_PASSPHRASE -b"[PASSPHARSE]"

3. Deploy maildog

3.1 Enable workflows on your forked repository

enable-github-actions-screenshot

Before Github can manage maildog, you need to enable it explicitly. Please visit the actions tab of your repository and enable it by clicking I understand my workflows, go ahead and enable them.

3.2 Run the Deploy workflow

Now, everything is ready. All you need is to push the production branch up with the changes you made previously. The deploy workflow will be triggered automatically whenever you push to the production branch:

# Push the production branch
git push --set-upstream origin production
# Check the deploy workflow status
gh workflow view --web deploy.yaml

3.3 Destroy maildog

You can delete everything deployed easily with the destroy workflow:

# Check the destroy workflow from Github
gh workflow view --web destroy.yaml

3.4 Monitor with Health check

maildog sends failed messages to the Dead Letter Queue (DLQ). The health workflow works by monitoring the alarm status configured to the DLQ every hour. You can enable it if needed:

#Enable the health workflow
gh workflow enable health.yaml