From 3b66e6d29f4b0aac4db2f87ebf68df50123170f5 Mon Sep 17 00:00:00 2001 From: kappa Date: Tue, 9 Sep 2025 09:28:27 +0900 Subject: [PATCH] Add CLAUDE.md configuration file for Claude Code integration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CLAUDE.md | 149 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..ed52c9e --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,149 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Common Development Commands + +### Infrastructure Management +```bash +# Initialize OpenTofu (required after cloning) +tofu init + +# Plan changes +tofu plan + +# Apply changes +tofu apply + +# Destroy infrastructure +tofu destroy +``` + +### Backend Setup (S3 + CloudFront Logs) +```bash +# Set up S3 backend and CloudFront logging buckets +./setup-backend.sh + +# Migrate state to S3 backend (one-time operation) +echo "yes" | tofu init -migrate-state +``` + +### Validation and Formatting +```bash +# Validate Terraform configuration +tofu validate + +# Format Terraform files +tofu fmt + +# Check syntax and validate variables +tofu plan -var-file=terraform.tfvars +``` + +### AWS Resource Verification +```bash +# Check CloudFront distribution status +aws cloudfront get-distribution --id E1XR8P4ENGP8RU --query 'Distribution.Status' --output text + +# List all CloudFront distributions +aws cloudfront list-distributions --query 'DistributionList.Items[*].[Id,Status,DistributionConfig.Enabled]' --output table + +# Check S3 backend state +aws s3 ls s3://aws-cf-terraform-state-535294143817/aws-cf/ + +# View CloudFront logs +aws s3 ls s3://aws-cf-cloudfront-logs-535294143817/cloudfront-logs/ --recursive +``` + +## Architecture Overview + +### Infrastructure Design +This is an AWS CloudFront CDN deployment using OpenTofu (Terraform fork) with the following key architectural decisions: + +**Primary Components:** +- **CloudFront Distribution**: Main CDN with custom origin server +- **WAF v2 Web ACL**: Security layer with rate limiting and AWS managed rules +- **S3 Backend**: Remote state storage with versioning and encryption +- **Optional CloudFormation Stack**: VPC and networking resources + +**Critical Configuration Constraints:** +- Origin server (`origin.servidor.it.com`) only supports HTTP, not HTTPS +- Using CloudFront default certificate (not custom ACM certificate) +- Route53 records disabled due to CAA restrictions +- DynamoDB state locking disabled due to permission constraints + +### File Structure and Responsibilities + +**Core Infrastructure:** +- `main.tf` - CloudFront distribution, origin configuration, cache behaviors, and optional CloudFormation stack +- `security.tf` - WAF Web ACL with rate limiting, managed rule sets, and security groups +- `variables.tf` - All configurable parameters with validation rules +- `outputs.tf` - CloudFront URLs, distribution IDs, and resource ARNs + +**Configuration Management:** +- `backend.tf` - S3 remote state configuration (no DynamoDB locking) +- `versions.tf` - OpenTofu/Terraform and provider version constraints +- `acm.tf` - ACM certificate configuration (currently disabled) +- `terraform.tfvars.example` - Variable configuration template + +**Operational Scripts:** +- `setup-backend.sh` - Automated S3 backend and logging bucket creation with proper permissions + +### Key Architectural Patterns + +**Multi-Environment Design:** +- Variables for `project_name` and `environment` enable multiple deployments +- Resource naming follows `${project_name}-${environment}-${resource}` pattern +- Tags applied consistently across all resources + +**Security-First Approach:** +- WAF protection with AWS managed rules and rate limiting +- S3 buckets with encryption, versioning, and public access blocking +- Security groups with principle of least privilege (when VPC enabled) + +**Cache Strategy:** +- Default behavior uses CachingDisabled policy for dynamic content +- API paths (`/api/*`) specifically configured with caching disabled +- Static content can be optimized by changing cache policy IDs + +**Conditional Resource Creation:** +- Most resources controlled by boolean variables for flexible deployment +- ACM certificates, Route53 records, and CloudFormation stacks can be toggled +- Allows gradual feature enablement as permissions are acquired + +## Important Configuration Notes + +### Critical Settings in terraform.tfvars +- `origin_protocol_policy = "http-only"` - **Do not change to HTTPS** (causes 504 errors) +- `create_acm_certificate = false` - Custom certificates fail due to CAA restrictions +- `enable_waf = true` - WAF is working and provides important security +- `create_route53_records = false` - DNS management disabled due to CAA restrictions + +### State Management +- Backend uses S3 without DynamoDB locking (single developer setup) +- State bucket: `aws-cf-terraform-state-535294143817` +- Logs bucket: `aws-cf-cloudfront-logs-535294143817` + +### Security Considerations +- WAF provides protection against common attacks and rate limiting +- Origin-to-CloudFront traffic is unencrypted (HTTP-only constraint) +- SSH access defaults to 0.0.0.0/0 in variables - **restrict in production** +- CloudFront logs stored in S3 with 90-day lifecycle policy + +### Performance Optimization +- Price class set to PriceClass_100 (US, Canada, Europe) +- Compression enabled for all content types +- Custom error pages redirect 404/403 to index.html for SPA support + +### Working vs Disabled Features +**Currently Working:** +- CloudFront distribution with HTTP origin +- WAF v2 with managed rules +- S3 logging and state storage +- Custom cache behaviors for API paths + +**Currently Disabled (can be enabled with proper permissions):** +- ACM custom certificates (CAA restrictions) +- Route53 DNS management (CAA restrictions) +- CloudFormation VPC stack (permission constraints) +- DynamoDB state locking (permission constraints) \ No newline at end of file