AWS Route 53 & CloudFront Subpath Setup
Host documentation at a custom subpath using AWS Route 53 and CloudFront for enterprise-grade infrastructure.
Overview
Deploy your documentation at a custom subpath such as yoursite.com/docs, yoursite.com/help, or any path you choose using AWS Route 53 for DNS management and CloudFront for content delivery. This guide provides a complete enterprise-grade setup with advanced caching, security, and global distribution.
Use any subpath: /docs, /help, /guide, etc. Replace /docs in examples with your path.
Architecture Overview
AWS CloudFront acts as a reverse proxy, routing traffic based on path patterns to either your documentation hosting or your main website.
High-Level Configuration Summary
You'll configure CloudFront behaviors to route traffic based on path patterns:
| Path Pattern | Cache Policy | Origin | Purpose |
|---|---|---|---|
/.well-known/* | CachingDisabled | Documentation | Domain verification |
/docs/* (or your subpath) | CachingOptimized | Documentation | Documentation pages |
/docs (or your subpath) | CachingOptimized | Documentation | Documentation root |
/dai-assets/_next/static/* | CachingOptimized | Documentation | Static assets |
Default (*) | CachingOptimized | Main Site | Landing page |
All behaviors must use origin request policy AllViewerExceptHostHeader.
Prerequisites
AWS Account
Active AWS account with billing enabled.
Domain in Route 53
Your domain managed in Route 53 (or ability to update DNS).
Staging URL
A staging URL for your main site (e.g., Vercel preview URL, Webflow staging).
Documentation Subdomain
Your documentation accessible at [SUBDOMAIN].documentationai.io.
Step 1: Create CloudFront Distribution
Navigate to CloudFront
Open the AWS Console and navigate to CloudFront.
Create Distribution
Click Create distribution.
Configure Origin
Set the Origin domain to [SUBDOMAIN].documentationai.io (replace with your actual subdomain).
Enable WAF
For Web Application Firewall (WAF), select Enable security protections.
Create
Leave other settings as default and click Create distribution.
Step 2: Add Main Site Origin
Your CloudFront distribution needs two origins: one for documentation and one for your main site.
Navigate to Origins
In your distribution, go to the Origins tab.
Find Staging URL
Locate your main site's staging URL:
- Vercel: Use your
.vercel.apppreview domain - Webflow: Use your
.webflow.iostaging domain - Netlify: Use your
.netlify.appdomain
Create Origin
Click Create origin and enter your staging URL as the Origin domain.
Save
Keep default settings and click Create origin.
After this step, you should have two origins in your distribution:
[SUBDOMAIN].documentationai.io- Documentationyour-site.vercel.app(or similar) - Main site
Step 3: Configure Behaviors
Behaviors control how CloudFront routes and caches requests based on URL patterns.
Behavior 1: Domain Verification Paths
Create a behavior for domain verification and SSL certificate provisioning.
Navigate to Behaviors
Go to the Behaviors tab in your distribution.
Create Behavior
Click Create behavior.
Configure Path
Set Path pattern to /.well-known/*.
Set Origin
Set Origin to your documentation origin ([SUBDOMAIN].documentationai.io).
Disable Caching
Set Cache policy to CachingDisabled.
Set Request Policy
Set Origin request policy to AllViewerExceptHostHeader.
Force HTTPS
Set Viewer protocol policy to Redirect HTTP to HTTPS.
Create
Click Create behavior.
Behavior 2: Documentation Root Path
Create a behavior for the documentation root (e.g., /docs).
Create Behavior
Click Create behavior again.
Set Path
Set Path pattern to your chosen subpath (e.g., /docs, /help, /guide).
Set Origin
Set Origin to your documentation origin ([SUBDOMAIN].documentationai.io).
Enable Caching
Set Cache policy to CachingOptimized.
Set Request Policy
Set Origin request policy to AllViewerExceptHostHeader.
Force HTTPS
Set Viewer protocol policy to Redirect HTTP to HTTPS.
Create
Click Create behavior.
Behavior 3: Documentation Wildcard Path
Create a behavior for all documentation pages (e.g., /docs/*).
Create Behavior
Click Create behavior.
Set Wildcard Path
Set Path pattern to your subpath with wildcard (e.g., /docs/*, /help/*, /guide/*) to match all nested pages.
Match Previous Settings
Use the same settings as Behavior 2:
- Origin: Documentation origin
- Cache policy: CachingOptimized
- Origin request policy: AllViewerExceptHostHeader
- Viewer protocol policy: Redirect HTTP to HTTPS
Create
Click Create behavior.
Behavior 4: Static Assets
Create a behavior for documentation static assets.
Create Behavior
Click Create behavior.
Set Asset Path
Set Path pattern to /dai-assets/_next/static/*.
Configure Caching
Use the same settings as the documentation behaviors:
- Origin: Documentation origin
- Cache policy: CachingOptimized
- Origin request policy: AllViewerExceptHostHeader
- Viewer protocol policy: Redirect HTTP to HTTPS
Create
Click Create behavior.
Behavior 5: Update Default Behavior
Modify the default behavior to route all other traffic to your main site.
Select Default
Find the Default (*) behavior and click Edit.
Change Origin
Change Origin to your main site staging URL origin.
Enable Caching
Set Cache policy to CachingOptimized.
Set Request Policy
Set Origin request policy to AllViewerExceptHostHeader.
Force HTTPS
Set Viewer protocol policy to Redirect HTTP to HTTPS.
Save
Click Save changes.
Verify Behavior Configuration
Your final behavior list should look like this (order matters):
/.well-known/*→ Documentation origin (CachingDisabled)/docs/*→ Documentation origin (CachingOptimized)/docs→ Documentation origin (CachingOptimized)/dai-assets/_next/static/*→ Documentation origin (CachingOptimized)Default (*)→ Main site origin (CachingOptimized)
Step 4: Test Your Distribution
Before connecting your domain, test the distribution using the CloudFront URL.
Find Distribution URL
In the General tab, copy the Distribution domain name (e.g., d123456abcdef.cloudfront.net).
Test Root
Visit https://d123456abcdef.cloudfront.net - should show your main site.
Test Documentation
Visit https://d123456abcdef.cloudfront.net/docs - should show your documentation.
Test Nested Page
Visit a documentation page like https://d123456abcdef.cloudfront.net/docs/getting-started/introduction.
Step 5: Connect Route 53
Now connect your custom domain to the CloudFront distribution.
Navigate to Route 53
Open Route 53 in the AWS Console.
Select Hosted Zone
Navigate to Hosted zones and select your domain.
Create Record
Click Create record.
Enable Alias
Toggle Alias to ON.
Route to CloudFront
Set Route traffic to → Alias to CloudFront distribution.
Select Distribution
Choose your CloudFront distribution from the dropdown.
Create Record
Click Create records.
Add www Subdomain (Optional)
Repeat the process above to create an alias record for www.yoursite.com pointing to the same CloudFront distribution.
Step 6: Configure SSL Certificate
CloudFront requires an SSL certificate for HTTPS.
Request Certificate
In your distribution, go to General → Settings → Edit.
Add Alternate Domain
Under Alternate domain names (CNAMEs), add your domain (e.g., yoursite.com).
Request Certificate
Click Request certificate to open AWS Certificate Manager.
Add Domain Names
Add your domain and www variant:
yoursite.comwww.yoursite.com
Validate Domain
Choose DNS validation and follow the prompts to add validation records to Route 53.
Wait for Validation
Certificate validation typically takes 5-30 minutes.
Attach Certificate
Return to CloudFront settings and select your validated certificate.
Save Changes
Click Save changes and wait for distribution to redeploy.
Verification and Testing
After DNS propagation (usually 5-60 minutes):
Test Main Domain
Visit https://yoursite.com - should display your main site.
Test Documentation
Visit https://yoursite.com/[SUBPATH] - should display documentation.
Test HTTPS
Verify the SSL certificate is valid and showing your domain.
Test Nested Pages
Navigate through multiple documentation pages.
Check Performance
Use browser DevTools to verify fast load times and proper caching.
Monitoring and Optimization
CloudWatch Metrics
Monitor your distribution performance in CloudWatch:
- Requests: Total number of requests
- BytesDownloaded: Total data transferred
- ErrorRate: 4xx and 5xx error rates
- OriginLatency: Response time from origins
Cache Hit Ratio
Optimize your cache hit ratio to reduce origin load and improve performance:
- Navigate to CloudFront → Monitoring
- Review Cache hit rate metric
- Aim for >80% cache hit rate for optimal performance
Invalidations
Clear cached content when you update documentation:
Create Invalidation
Go to Invalidations tab → Create invalidation.
Specify Paths
Enter paths to invalidate:
/[SUBPATH]/*- All documentation/[SUBPATH]/specific-page- Single page
Submit
Click Create invalidation (usually completes in 1-5 minutes).
Troubleshooting
Cost Optimization
Data Transfer
CloudFront charges for data transfer out to the internet. Optimize costs by:
- Enabling compression for text-based content
- Using appropriate cache durations
- Minimizing redirects and unnecessary requests
Request Pricing
CloudFront charges per 10,000 requests. Reduce costs by:
- Maximizing cache hit ratios
- Combining small files where possible
- Using efficient image formats (WebP, AVIF)
Free Tier
AWS Free Tier includes:
- 1 TB data transfer out per month (first 12 months)
- 10,000,000 HTTP/HTTPS requests per month (first 12 months)
Advanced Configuration
Custom Error Pages
Configure custom error responses:
Navigate to Error Pages
Go to Error pages tab → Create custom error response.
Configure 404
Set HTTP error code to 404 and customize the response.
Add More Errors
Repeat for 403, 500, 502, 503, 504 as needed.
Geographic Restrictions
Restrict content by geography:
Navigate to Restrictions
Go to Restrictions tab → Edit.
Enable Restrictions
Choose whitelist or blacklist and select countries.
Save
Click Save changes.
Origin Shield
Enable Origin Shield for additional caching layer:
Edit Origin
Go to Origins → Select origin → Edit.
Enable Shield
Enable Origin Shield and select optimal region.
Save
Click Save changes.
Next Steps
After successfully deploying your documentation with AWS:
- Set up CloudWatch alarms for errors and performance
- Configure AWS WAF rules for security
- Enable CloudFront access logging for analytics
- Document your configuration for team members
- Create runbooks for common maintenance tasks
✅ Your documentation is now live on AWS!
Last updated today