AWS Route 53 & CloudFront
Proxy /docs traffic through AWS CloudFront and Route 53 to your Jamdesk site. Includes distribution setup, origin configuration, and cache behavior rules.
Set up a CloudFront distribution to forward /docs/* to your Jamdesk site, with Route 53 for DNS. Takes about 15 minutes.
Prerequisites
- An AWS account with CloudFront and Route 53 access
- Your domain managed in Route 53 (or ability to update DNS elsewhere)
- Your Jamdesk subdomain (found in dashboard settings)
- Your custom domain registered and DNS-verified in the Jamdesk dashboard
If you use a custom subpath instead of the default /docs, replace /docs/* in the cache behavior path pattern (Step 3) with your subpath. Update the distribution again after any rename in the dashboard.
Step 1: Create a CloudFront Distribution
- Open the CloudFront console
- Click Create Distribution
- Configure the origin:
| Setting | Value |
|---|---|
| Origin domain | YOUR_SLUG.jamdesk.app |
| Protocol | HTTPS only |
| Name | jamdesk-docs-origin |
Replace YOUR_SLUG with your Jamdesk subdomain.
Step 2: Configure Origin Settings
Add custom headers in the origin settings to identify your domain:
| Header name | Value |
|---|---|
X-Forwarded-Host | yoursite.com |
X-Jamdesk-Forwarded-Host | yoursite.com |
These headers tell Jamdesk which domain is making the request.
This step is required. Skipping it fails quietly. The AllViewerExceptHostHeader policy (next step) only forwards headers your visitor's browser sent. It does not add new ones. X-Jamdesk-Forwarded-Host reaches Jamdesk only as an origin custom header. Without it, requests still succeed, but pages serve noindex with canonical links pointing at YOUR_SLUG.jamdesk.app instead of your domain.
Static origin headers can't vary per request. To serve multiple alternate domain names from one distribution, use a CloudFront Function on viewer request instead. Have it set request.headers['x-jamdesk-forwarded-host'] = { value: request.headers.host.value }.
Step 3: Create Cache Behaviors
Add behaviors to route /docs/* and asset requests to your Jamdesk origin:
- Go to the Behaviors tab
- Click Create Behavior
- Create three behaviors with these settings:
| Path pattern | Origin | Cache policy | Origin request policy |
|---|---|---|---|
/docs/* | jamdesk-docs-origin | CachingOptimized | AllViewerExceptHostHeader |
/_next/* | jamdesk-docs-origin | CachingOptimized | AllViewerExceptHostHeader |
/_jd/* | jamdesk-docs-origin | CachingOptimized | AllViewerExceptHostHeader |
Set Viewer protocol policy to Redirect HTTP to HTTPS for all three.
Every behavior is required. /_next/* and /_jd/* serve the JavaScript, CSS, fonts, and images your docs pages load. The AllViewerExceptHostHeader policy forwards the viewer's request headers (everything except Host, which CloudFront reserves for the origin). Set it on all three.
Step 4: Add Alternate Domain Name
- In the General tab, click Edit
- Under Alternate domain name (CNAME), add
yoursite.com - Select or request an SSL certificate for your domain
Step 5: Configure Route 53
Create an alias record pointing to your CloudFront distribution:
- Open the Route 53 console
- Select your hosted zone
- Click Create Record
- Configure:
| Setting | Value |
|---|---|
| Record name | yoursite.com (or leave blank for apex) |
| Record type | A |
| Alias | Yes |
| Route traffic to | CloudFront distribution |
| Distribution | Select your distribution |
Step 6: Verify
Wait for DNS propagation (usually 5-15 minutes). Then visit https://yoursite.com/docs and confirm your documentation loads.
Complete CloudFront Configuration Summary
Distribution Settings:
├── Origin: YOUR_SLUG.jamdesk.app
│ ├── Custom Header: X-Forwarded-Host = yoursite.com
│ └── Custom Header: X-Jamdesk-Forwarded-Host = yoursite.com
├── Behavior: /docs/*
│ ├── Cache Policy: CachingOptimized
│ └── Origin Request Policy: AllViewerExceptHostHeader
├── Behavior: /_next/*
│ ├── Cache Policy: CachingOptimized
│ └── Origin Request Policy: AllViewerExceptHostHeader
├── Behavior: /_jd/*
│ ├── Cache Policy: CachingOptimized
│ └── Origin Request Policy: AllViewerExceptHostHeader
└── Alternate Domain: yoursite.com (with SSL certificate)Troubleshooting
Check that the origin domain is exactly YOUR_SLUG.jamdesk.app, without the https:// prefix.
Verify the Viewer protocol policy is set to "Redirect HTTP to HTTPS" and your SSL certificate is valid.
Create a CloudFront invalidation for /docs/* to clear cached content after publishing changes.
If you see "Domain is not authorized to serve this content":
- Verify your domain is registered in the Jamdesk dashboard
- Complete DNS verification (TXT record) for your domain
- Set the
X-Forwarded-HostandX-Jamdesk-Forwarded-Hostcustom headers in your origin configuration - Check that your domain maps to the correct project
The domain must be verified before CloudFront can serve documentation.
Preflight fetches /_jd/preflight on your live domain and checks what reached Jamdesk. If it reports your proxy "doesn't identify itself," CloudFront is reaching Jamdesk without X-Jamdesk-Forwarded-Host. Recheck the origin custom header in Step 2. See Custom domain only for what each preflight message means.