Create a distribution with your current host as the origin for the Default (*) behavior, add the Ferndesk origin and behaviors above, and add your domain with an SSL certificate from AWS Certificate Manager in the US East (N. Virginia) region. Then point your domain at the distribution, for example with an alias record in Route 53.
Put your help center on a sub-folder with AWS CloudFront
Serve your help center at a path on a site behind Amazon CloudFront, such as yourcompany.com/help, by adding Ferndesk as a second origin with three cache behaviors and a small CloudFront Function. Your domain must already point at the CloudFront distribution.
Needs a payment method on file, which a trial with a card meets. Owners and admins can change this.
Set it up
Set the sub-folder in Ferndesk
In Help Center > Customize > Custom Domain, choose Custom sub-folder, enter your site's domain and a path such as /help, and click Configure subdirectory. Copy the Proxy host we show you (it looks like yourcompany.hc.ferndesk.com). The examples below use /help and www.yourcompany.com; replace them with your own.
Create the function
In CloudFront > Functions, create a function with the cloudfront-js-2.0 runtime, paste the code below, and publish it. It removes /help from the path before the request reaches Ferndesk. If you use another path, change help in the code.
function handler(event) {
var request = event.request;
request.uri = request.uri.replace(/^\/help/, '') || '/';
return request;
}Add Ferndesk as an origin
In your distribution's Origins tab, create an origin with the proxy host as its origin domain and the protocol set to HTTPS only. Add two custom headers to it: X-Ferndesk-Base-Path set to your path, and X-Ferndesk-Original-Host set to your site's host, such as www.yourcompany.com.
Add three behaviors
In the Behaviors tab, create a behavior for each of /help, /help/* and /_ferndesk/*, all pointing at the Ferndesk origin. Give each one these settings:
Viewer protocol policy: Redirect HTTP to HTTPS
Allowed HTTP methods: GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
Cache policy: CachingDisabled
Origin request policy: AllViewerExceptHostHeader
On the /help and /help/* behaviors, under Function associations, attach the function as the Viewer request function. Leave /_ferndesk/* without it. Your site keeps the Default (*) behavior. Wait for the distribution to finish deploying.
If you manage the distribution with CloudFormation, the same settings look like this:
# The function (a separate resource in the same template)
FerndeskStripHelp:
Type: AWS::CloudFront::Function
Properties:
Name: ferndesk-strip-help
AutoPublish: true
FunctionConfig:
Comment: Remove /help before forwarding to Ferndesk
Runtime: cloudfront-js-2.0
FunctionCode: |
function handler(event) {
var request = event.request;
request.uri = request.uri.replace(/^\/help/, '') || '/';
return request;
}
# Part of DistributionConfig in the AWS::CloudFront::Distribution resource
Origins:
- Id: ferndesk
DomainName: PROXY_HOST
CustomOriginConfig:
OriginProtocolPolicy: https-only
OriginSSLProtocols: [TLSv1.2]
OriginCustomHeaders:
- HeaderName: X-Ferndesk-Base-Path
HeaderValue: /help
- HeaderName: X-Ferndesk-Original-Host
HeaderValue: www.yourcompany.com
# ...your site's existing origin stays here
CacheBehaviors:
- PathPattern: /help
TargetOriginId: ferndesk
ViewerProtocolPolicy: redirect-to-https
AllowedMethods: [GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE]
CachedMethods: [GET, HEAD]
CachePolicyId: 4135ea2d-6df8-44a3-9df3-4b5a84be39ad # CachingDisabled
OriginRequestPolicyId: b689b0a8-53d0-40ab-baf2-68738e2966ac # AllViewerExceptHostHeader
FunctionAssociations:
- EventType: viewer-request
FunctionARN: !GetAtt FerndeskStripHelp.FunctionMetadata.FunctionARN
- PathPattern: /help/*
TargetOriginId: ferndesk
ViewerProtocolPolicy: redirect-to-https
AllowedMethods: [GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE]
CachedMethods: [GET, HEAD]
CachePolicyId: 4135ea2d-6df8-44a3-9df3-4b5a84be39ad
OriginRequestPolicyId: b689b0a8-53d0-40ab-baf2-68738e2966ac
FunctionAssociations:
- EventType: viewer-request
FunctionARN: !GetAtt FerndeskStripHelp.FunctionMetadata.FunctionARN
- PathPattern: /_ferndesk/*
TargetOriginId: ferndesk
ViewerProtocolPolicy: redirect-to-https
AllowedMethods: [GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE]
CachedMethods: [GET, HEAD]
CachePolicyId: 4135ea2d-6df8-44a3-9df3-4b5a84be39ad
OriginRequestPolicyId: b689b0a8-53d0-40ab-baf2-68738e2966acWhat each setting is for:
AllViewerExceptHostHeader passes cookies, query strings and headers on to Ferndesk, and sends the proxy host as the
Hostheader. If CloudFront forwards your ownHostheader instead, every page fails with a 403 or 502 error. You don't need to sendX-Forwarded-Host: theX-Ferndesk-Original-Hostheader does that job.All HTTP methods are needed because sign-in, AI answers and the feedback form send
POSTrequests under/help.CachingDisabled keeps pages for signed-in readers private. Ferndesk sets its own cache headers.
The function is needed because Ferndesk expects paths without
/help. Without it, articles load but sign-in, feedback, AI answers and the sitemap don't.
This setup follows AWS's CloudFront documentation. We haven't tested it on CloudFront ourselves, so if something doesn't work, email [email protected] with your config and the address that fails.
Check that it works
Open https://www.yourcompany.com/help. Your help center should load with its styling, and links between articles should stay on your domain. If something is off, see Troubleshoot your help center.
Common questions
My site isn't behind CloudFront yet
Can I use an Application Load Balancer instead?
Not on its own. A load balancer can only send requests to your own servers, private IP addresses or Lambda functions, not to a public hostname like the proxy host. Put CloudFront in front of it, or run Nginx on your servers and follow the Nginx guide.
The help center loads without styling
The /_ferndesk/* behavior is missing or points at your site's origin. It serves the help center's scripts and styles from the root of your domain.
Every page shows a 403 or 502 error
CloudFront is forwarding your site's Host header. Set the origin request policy to AllViewerExceptHostHeader on all three behaviors, not AllViewer.
For a subdomain instead, or for other hosts, see Connect a custom domain to your help center.