# Fullstack Docusaurus CloudFront Template Docusaurus static site with flexible authentication options on AWS CloudFront. ## Features - **Docusaurus**: Modern static site generator - **AWS CloudFront**: Global CDN distribution - **S3 Static Hosting**: Secure static file hosting - **Flexible Authentication**: 4 authentication modes - **None** (`none`): Public access - **Basic** (`basic`): CloudFront Functions - **Cognito** (`cognito`): Lambda@Edge + OAuth2 - **IP Restriction** (`ip`): AWS WAF - **Infrastructure as Code**: Terraform managed - **CI/CD**: GitHub Actions auto-deployment ## Architecture ``` User -> Route53 -> CloudFront -> [Authentication] -> S3 (Docusaurus Static Files) | +-> Basic: CloudFront Functions +-> Cognito: Lambda@Edge + Cognito +-> IP: AWS WAF ``` ## Prerequisites - AWS Account - [mise](https://mise.jdx.dev/) (recommended for version management) - OR Terraform >= 1.9.8 manually installed - OR Node.js >= 20 manually installed - Route53 Hosted Zone - GitHub Account (for CI/CD) ## Quick Start ### 0. Install mise (Recommended) ```bash # Install mise curl https://mise.run | sh # Trust the project configuration mise trust # Install all tools (Terraform 1.9.8 + Node.js 20) mise install ``` ### 1. Infrastructure Setup ```bash cd infra # For Cognito authentication, install Lambda dependencies first mise run lambda-install cd environments/dev # Configure Terraform variables cp terraform.tfvars.example terraform.tfvars # Edit terraform.tfvars # Initialize and deploy with mise mise exec -- terraform init mise exec -- terraform plan mise exec -- terraform apply # Or use mise tasks (from infra/ directory) cd .. mise run init mise run plan mise run apply ``` **Without mise:** ```bash cd infra/environments/dev terraform init terraform plan terraform apply ``` ### 2. Build Docusaurus Site **With mise:** ```bash cd docs-site # Install dependencies mise run install # Start development server mise run dev # Production build mise run build ``` **Without mise:** ```bash cd docs-site npm install npm start npm run build ``` ### 3. Setup GitHub Actions Add these Secrets to your GitHub repository: - `AWS_ROLE_ARN`: IAM Role ARN from Terraform output - `AWS_S3_BUCKET`: S3 bucket name - `AWS_CLOUDFRONT_DISTRIBUTION_ID`: CloudFront Distribution ID ### 4. Deploy ```bash # Auto-deploy on push to main branch git add . git commit -m "docs: Update documentation" git push origin main ``` ## Directory Structure ``` fullstack-docusaurus-cloudfront/ � README.md # This file � infra/ # Terraform infrastructure � � main.tf # Data sources � � s3.tf # S3 bucket � � cloudfront.tf # CloudFront + ACM + Route53 � � cloudfront_functions.tf # Basic auth (CloudFront Functions) � � cognito.tf # Cognito + Lambda@Edge � � waf.tf # WAF for IP restriction � � iam.tf # GitHub Actions IAM � � variables.tf # Variable definitions � � outputs.tf # Output definitions � � providers.tf # Provider configuration � � terraform.tfvars.example # Configuration example � � lambda/ # Lambda@Edge function � � index.js � � package.json � docs-site/ # Docusaurus application � � package.json � � docusaurus.config.ts � � sidebars.ts � � tsconfig.json � � docs/ � � � intro.md � � src/ � � � css/ � � � � custom.css � � � pages/ � � � index.tsx � � static/ � � img/ � .github/ # GitHub Actions � � workflows/ � � deploy.yml � .gitignore ``` ## Authentication Configuration Edit `infra/environments/dev/terraform.tfvars` to select authentication type: ### 1. No Authentication (Public Access) ```hcl authentication_type = "none" ``` ### 2. Basic Authentication (CloudFront Functions) ```hcl authentication_type = "basic" basic_auth_username = "admin" basic_auth_password = "your-secure-password" ``` - **Implementation**: CloudFront Functions - **Cost**: Low ($0.10/1M requests) - **Limitations**: Single user only - **Use Case**: Simple internal documentation ### 3. Cognito Authentication (Lambda@Edge + OAuth2) ```hcl authentication_type = "cognito" cognito_user_pool_name = "docs-users" cognito_callback_urls = [ "https://docs.example.com/oauth2/callback" ] cognito_logout_urls = [ "https://docs.example.com" ] ``` - **Implementation**: Lambda@Edge + AWS Cognito - **Cost**: Medium (Lambda@Edge execution) - **Features**: Multi-user, email authentication, OAuth2 - **Use Case**: Production user management **Requires Lambda dependencies:** ```bash # With mise cd infra mise run lambda-install # Without mise cd infra/modules/docusaurus/lambda npm install ``` ### 4. IP Restriction (AWS WAF) ```hcl authentication_type = "ip" allowed_ip_ranges = [ "203.0.113.0/24", # Office IP "198.51.100.0/24" # VPN IP ] ``` - **Implementation**: AWS WAF - **Cost**: Medium ($5/month + $1/rule) - **Limitations**: IP-based access control only - **Use Case**: Corporate network access only ## Customization ### Domain Configuration `infra/environments/dev/terraform.tfvars`: ```hcl domain_name = "docs.example.com" hosted_zone_id = "Z1234567890ABC" ``` ### Docusaurus Customization Customize `docs-site/docusaurus.config.ts`: - Site title and tagline - Navigation - Theme colors - Plugins ## Cost Estimation (Monthly, Low Traffic) ### Base Cost (All Authentication Types) - **S3**: ~$0.50 (10GB storage, 10k requests) - **CloudFront**: ~$1.00 (10GB transfer, 100k requests) - **Route53**: $0.50 (hosted zone) ### Authentication-Specific Costs | Authentication | Additional Cost | Description | |---------------|----------------|-------------| | **none** | $0 | No authentication | | **basic** | ~$0.10 | CloudFront Functions (1M requests) | | **cognito** | ~$0.50 | Lambda@Edge + Cognito (free tier) | | **ip** | ~$6.00 | WAF ($5/month + $1/rule) | **Total**: $2.00 ~ $8.00/month ## Security - S3 bucket is private (CloudFront OAC only) - HTTPS enforced (ACM certificate) - Authentication options (Basic/Cognito/IP) - Lambda@Edge JWT verification (Cognito mode) - HttpOnly and Secure cookie flags (Cognito mode) ## Troubleshooting ### Lambda@Edge Errors Lambda@Edge logs are in CloudWatch Logs (**us-east-1 region**): ```bash aws logs tail /aws/lambda/us-east-1. --follow --region us-east-1 ``` ### CloudFront Cache Clear ```bash aws cloudfront create-invalidation \ --distribution-id \ --paths "/*" ``` ### Cognito Authentication Errors 1. Verify callback URLs match exactly 2. Check Cognito User Pool domain configuration 3. Ensure users are created and confirmed ### Basic Authentication Issues - Verify username and password in `terraform.tfvars` - CloudFront Functions take a few minutes to propagate - Test with `curl -u username:password https://docs.example.com` ### WAF IP Restriction - Add your current IP: `curl ifconfig.me` - Update `allowed_ip_ranges` in `infra/environments/dev/terraform.tfvars` - Re-run `terraform apply` from `infra/environments/dev/` ## License MIT License ## References - [Docusaurus](https://docusaurus.io/) - [AWS CloudFront](https://aws.amazon.com/cloudfront/) - [CloudFront Functions](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-functions.html) - [Lambda@Edge](https://docs.aws.amazon.com/lambda/latest/dg/lambda-edge.html) - [AWS Cognito](https://aws.amazon.com/cognito/) - [AWS WAF](https://aws.amazon.com/waf/)