serverless-website-domain
A Serverless plugin specifically designed to set up domains for your static website (not API Gateway). It creates Route 53 entries that point to your Cloudfront Distribution.
Features:
- Maps both HTTP & HTTPS non-www variants of your domain to https://www.yourdomain.com
- Works alongside other popular plugins:
- serverless-certificate-creator
- serverless-s3-sync
- serverless-cloudfront-invalidate
- Simple examples in /examples folder
Prerequisites
This plugin requires that you use at serverless v3 as it relies on variableResolutionMode 20210326
Before running you must manually create a Hosted Zone in Route 53. with domain name yourdomain.com
How to use?
Add the plugin to your serverless.yml
plugins:
-serverless-website-domain
Add plugin configuration to serverless.yml
custom:
domainComponents: #Key not needed, just used as example.
withWWW: www.${self:custom.domainComponents.withoutWWW}
withoutWWW: yourdomain.com
websiteDomain:
disabled: false # defaults to false. enable to prevent DNS changes if needed (e.g. per env)
cloudfrontOutputKey: 'yourCloudfrontDomainName'
domain: ${self:custom.domainComponents.withWWW} #must be hostedZoneDomain or subdomain of it
edgeLambda:
basicAuthCredentials: ${env:BASIC_AUTH_CREDENTIALS} #e.g user/password
redirect:
from: ${self:custom.domainComponents.withoutWWW}
to: https://${self:custom.domainComponents.withWWW}
variablesResolutionMode: 20210326
resources:
Outputs:
yourCloudfrontDomainName:
Value:
'Fn::GetAtt': [ CloudFrontDistribution, DomainName ]
Resources
CloudFrontDistribution:
Type: AWS::CloudFront::Distribution
Properties:
DistributionConfig:
Aliases:
- ${self:custom.domainComponents.withWWW}
- ${self:custom.domainComponents.withoutWWW}
DefaultCacheBehavior:
LambdaFunctionAssociations:
- EventType: viewer-request
LambdaFunctionARN: ${websiteDomain(edgeLambdaArn)}
ViewerCertificate:
#manually specify ARN:
AcmCertificateArn: ${certificate(${self:custom.customCertificate.certificateName}):CertificateArn}
How to run
To create the domain
serverless create-edge-lambda #If you are using custom.websiteDomain.edgeLambda
serverless deploy #Called in after:deploy hook
There are also other manual commands you can run:
serverless remove-domain
serverless create-domain
serverless remove-edge-lambda
create-domain
will also be called automatically by serverless deploy
during the after
If you are using alongside serverless-certificate-creator you should call serverless create-cert
before serverless create-redirect
. You must also ensure that you include both www & non-www variants in subjectAlternativeNames. E.G:
customCertificate:
certificateName: ${self:custom.domainComponents.withWWW}
hostedZoneNames: ${env:AWS_ROUTE53_HOSTED_ZONE_DOMAIN_NAME}.
subjectAlternativeNames:
- '${self:custom.domainComponents.withoutWWW}'
Examples
It's highly recommended to look at the files in the examples directory to start with. It shows how to use this plugin alongside serverless-certificate-creator, serverless-s3-sync & serverless-cloudfront-invalidate for a full solution including environment specific domains (e.g env.yourdomain.com).
Parameters
Name | Required | Data Type | Default | Description |
---|---|---|---|---|
cloudfrontOutputKey | Y | String | Should match key in resource.outputs which contains Cloudfront domain name (e.g 'Fn::GetAtt': [ CloudFrontDistribution, DomainName ]). | |
domain | Y | String | The domain you want to create. (e.g sub.yourdomain.com or yourdomain.com). Must exist under hosted zone of hostedZoneId. | |
edgeLambda | N | Object | NULL | Parent property |
basicAuthCredentials | N | String | NULL | Specify to guard website with basic auth. Separate username & password with '/' or use 'false' to disable. |
redirect | N | Object | NULL | Parent property. |
redirect.from | Y | Object | NULL | Required if .redirect set. 'It will be matched against lambda request.host[0]. It will also create a route 53 A & AAAA record for it. If you want to redirect from yourdomain.com to www.yourdomain.com just enter 'yourdomain.com' here. |
redirect.to | Y | Object | NULL | Required if .redirect set. It is the full destination URL including protocol. (E.G https://www.yourdomain.com) . |