fix: merge staging and correct CloudFront function logic for MkDocs

aleph · claude · aleph · commit a728f87a5886 · 2025-10-25T21:11:41.000-06:00
Merge changes from staging branch and fix the URL rewriting logic to correctly handle MkDocs directory URLs. Changes: - Merge staging branch (commits a111f61, e9b294a) - Remove duplicate cloudfront-function.tf (use unified url_rewrite function) - Fix url_rewrite function: change '.html' to '/index.html' for URLs without extension - Update documentation to reflect correct behavior - Integrate mkdocs.yml changes from staging The corrected logic now properly handles MkDocs use_directory_urls: - /meetups → /meetups/index.html (was incorrectly /meetups.html) - /meetups/ → /meetups/index.html (already correct) This ensures all directory URLs work correctly in both production and staging. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/docs/URL_FIX_DOCUMENTATION.md b/docs/URL_FIX_DOCUMENTATION.md
@@ -0,0 +1,96 @@
+# Fix para URLs sin extensión .html en producción
+
+## Problema
+Los enlaces funcionaban correctamente en local pero no en producción. Por ejemplo:
+- ❌ `https://pythoncdmx.org/meetups/` no funcionaba
+- ✅ `https://pythoncdmx.org/meetups/index.html` sí funcionaba
+
+## Causa
+El problema se debía a que CloudFront no estaba configurado para manejar URLs sin extensión `.html`. Cuando MkDocs genera el sitio con `use_directory_urls: true`, crea URLs como `/meetups/` que apuntan a `/meetups/index.html`, pero CloudFront no sabía cómo resolver estas URLs.
+
+## Solución Implementada
+
+### 1. Configuración en mkdocs.yml
+```yaml
+# URL configuration
+use_directory_urls: true
+```
+
+### 2. CloudFront Function
+Se agregó una función CloudFront que maneja automáticamente las URLs sin extensión:
+
+```javascript
+function handler(event) {
+    var request = event.request;
+    var uri = request.uri;
+
+    // If the URI ends with a slash, append index.html
+    if (uri.endsWith('/')) {
+        request.uri = uri + 'index.html';
+    }
+    // If the URI doesn't have an extension, append /index.html
+    else if (!uri.includes('.') && !uri.endsWith('/')) {
+        request.uri = uri + '/index.html';
+    }
+
+    return request;
+}
+```
+
+### 3. Asociación con Cache Behaviors
+La función se asoció con todos los cache behaviors de CloudFront para asegurar consistencia.
+
+## Archivos Modificados
+
+1. **mkdocs.yml**: Agregada configuración `use_directory_urls: true`
+2. **terraform/cloudfront.tf**: 
+   - Agregada CloudFront Function `url_rewrite`
+   - Asociada la función con todos los cache behaviors
+3. **terraform/cloudfront-staging.tf**:
+   - Aplicada la misma CloudFront Function a staging
+   - Asociada la función con todos los cache behaviors de staging
+
+## Despliegue
+
+Para aplicar estos cambios:
+
+1. **Aplicar cambios de Terraform**:
+   ```bash
+   cd terraform
+   terraform plan
+   terraform apply
+   ```
+
+2. **Desplegar el sitio**:
+   ```bash
+   # Los cambios se aplicarán automáticamente en el próximo deploy
+   git push origin main
+   ```
+
+## Verificación
+
+Después del despliegue, verificar que funcionen:
+
+### Producción
+- ✅ `https://pythoncdmx.org/meetups/`
+- ✅ `https://pythoncdmx.org/meetups/index.html`
+- ✅ `https://pythoncdmx.org/about/`
+- ✅ `https://pythoncdmx.org/about/index.html`
+
+### Staging
+- ✅ `https://staging.pythoncdmx.org/meetups/`
+- ✅ `https://staging.pythoncdmx.org/meetups/index.html`
+- ✅ `https://staging.pythoncdmx.org/about/`
+- ✅ `https://staging.pythoncdmx.org/about/index.html`
+
+## Notas Técnicas
+
+- La CloudFront Function se ejecuta en el edge, por lo que tiene latencia mínima
+- La función solo modifica la URI si es necesario, sin afectar assets estáticos
+- Los cache behaviors mantienen sus configuraciones originales de TTL
+- La solución es compatible con el comportamiento existente de MkDocs
+
+## Referencias
+
+- [MkDocs use_directory_urls documentation](https://www.mkdocs.org/user-guide/configuration/#use_directory_urls)
+- [CloudFront Functions documentation](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-functions.html)
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -11,6 +11,9 @@ repo_url: https://github.com/PythonMexico/pythonCDMX/
 # Copyright
 copyright: Copyright &copy; 2025 Python CDMX
 
+# URL configuration
+use_directory_urls: true
+
 # Theme configuration
 theme:
   name: material
diff --git a/terraform/cloudfront-function.tf b/terraform/cloudfront-function.tf
diff --git a/terraform/cloudfront-staging.tf b/terraform/cloudfront-staging.tf
@@ -7,6 +7,9 @@ resource "aws_cloudfront_origin_access_control" "website_staging" {
   signing_protocol                  = "sigv4"
 }
 
+# CloudFront Function for staging (reuse the same function as production)
+# Note: CloudFront Functions are global, so we can reference the same function
+
 # CloudFront distribution for staging
 resource "aws_cloudfront_distribution" "website_staging" {
   enabled             = true
@@ -39,14 +42,14 @@ resource "aws_cloudfront_distribution" "website_staging" {
 
     viewer_protocol_policy = "redirect-to-https"
     min_ttl                = 0
-    default_ttl            = 300  # 5 minutes - shorter cache for staging
-    max_ttl                = 3600 # 1 hour - shorter cache for staging
+    default_ttl            = 300     # 5 minutes - shorter cache for staging
+    max_ttl                = 3600    # 1 hour - shorter cache for staging
     compress               = true
 
-    # Associate CloudFront Function for directory index rewriting
+    # Associate CloudFront Function for URL rewriting (same as production)
     function_association {
       event_type   = "viewer-request"
-      function_arn = aws_cloudfront_function.directory_index_staging.arn
+      function_arn = aws_cloudfront_function.url_rewrite.arn
     }
   }
 
@@ -66,9 +69,15 @@ resource "aws_cloudfront_distribution" "website_staging" {
 
     viewer_protocol_policy = "redirect-to-https"
     min_ttl                = 0
-    default_ttl            = 1800 # 30 minutes
-    max_ttl                = 7200 # 2 hours
+    default_ttl            = 1800    # 30 minutes
+    max_ttl                = 7200    # 2 hours
     compress               = true
+
+    # Associate CloudFront Function for URL rewriting
+    function_association {
+      event_type   = "viewer-request"
+      function_arn = aws_cloudfront_function.url_rewrite.arn
+    }
   }
 
   # Cache behavior for static assets (JS) - shorter cache for staging
@@ -87,9 +96,15 @@ resource "aws_cloudfront_distribution" "website_staging" {
 
     viewer_protocol_policy = "redirect-to-https"
     min_ttl                = 0
-    default_ttl            = 1800 # 30 minutes
-    max_ttl                = 7200 # 2 hours
+    default_ttl            = 1800    # 30 minutes
+    max_ttl                = 7200    # 2 hours
     compress               = true
+
+    # Associate CloudFront Function for URL rewriting
+    function_association {
+      event_type   = "viewer-request"
+      function_arn = aws_cloudfront_function.url_rewrite.arn
+    }
   }
 
   # Cache behavior for images - shorter cache for staging
@@ -108,9 +123,15 @@ resource "aws_cloudfront_distribution" "website_staging" {
 
     viewer_protocol_policy = "redirect-to-https"
     min_ttl                = 0
-    default_ttl            = 3600  # 1 hour
-    max_ttl                = 86400 # 24 hours
+    default_ttl            = 3600    # 1 hour
+    max_ttl                = 86400   # 24 hours
     compress               = true
+
+    # Associate CloudFront Function for URL rewriting
+    function_association {
+      event_type   = "viewer-request"
+      function_arn = aws_cloudfront_function.url_rewrite.arn
+    }
   }
 
   # Custom error responses for SPA-like behavior
diff --git a/terraform/cloudfront.tf b/terraform/cloudfront.tf
@@ -7,6 +7,31 @@ resource "aws_cloudfront_origin_access_control" "website" {
   signing_protocol                  = "sigv4"
 }
 
+# CloudFront Function to handle directory URLs for MkDocs
+resource "aws_cloudfront_function" "url_rewrite" {
+  name    = "pythoncdmx-url-rewrite"
+  runtime = "cloudfront-js-1.0"
+  comment = "Rewrite directory URLs to include index.html for MkDocs"
+  publish = true
+  code    = <<-EOT
+function handler(event) {
+    var request = event.request;
+    var uri = request.uri;
+
+    // If the URI ends with a slash, append index.html
+    if (uri.endsWith('/')) {
+        request.uri = uri + 'index.html';
+    }
+    // If the URI doesn't have an extension, append /index.html
+    else if (!uri.includes('.') && !uri.endsWith('/')) {
+        request.uri = uri + '/index.html';
+    }
+
+    return request;
+}
+EOT
+}
+
 # CloudFront distribution
 resource "aws_cloudfront_distribution" "website" {
   enabled             = true
@@ -39,14 +64,14 @@ resource "aws_cloudfront_distribution" "website" {
 
     viewer_protocol_policy = "redirect-to-https"
     min_ttl                = 0
-    default_ttl            = 3600  # 1 hour
-    max_ttl                = 86400 # 24 hours
+    default_ttl            = 3600    # 1 hour
+    max_ttl                = 86400   # 24 hours
     compress               = true
 
-    # Associate CloudFront Function for directory index rewriting
+    # Associate CloudFront Function for URL rewriting
     function_association {
       event_type   = "viewer-request"
-      function_arn = aws_cloudfront_function.directory_index.arn
+      function_arn = aws_cloudfront_function.url_rewrite.arn
     }
   }
 
@@ -66,9 +91,15 @@ resource "aws_cloudfront_distribution" "website" {
 
     viewer_protocol_policy = "redirect-to-https"
     min_ttl                = 0
-    default_ttl            = 86400    # 24 hours
+    default_ttl            = 86400   # 24 hours
     max_ttl                = 31536000 # 1 year
     compress               = true
+
+    # Associate CloudFront Function for URL rewriting
+    function_association {
+      event_type   = "viewer-request"
+      function_arn = aws_cloudfront_function.url_rewrite.arn
+    }
   }
 
   ordered_cache_behavior {
@@ -86,9 +117,15 @@ resource "aws_cloudfront_distribution" "website" {
 
     viewer_protocol_policy = "redirect-to-https"
     min_ttl                = 0
-    default_ttl            = 86400    # 24 hours
+    default_ttl            = 86400   # 24 hours
     max_ttl                = 31536000 # 1 year
     compress               = true
+
+    # Associate CloudFront Function for URL rewriting
+    function_association {
+      event_type   = "viewer-request"
+      function_arn = aws_cloudfront_function.url_rewrite.arn
+    }
   }
 
   ordered_cache_behavior {
@@ -106,9 +143,15 @@ resource "aws_cloudfront_distribution" "website" {
 
     viewer_protocol_policy = "redirect-to-https"
     min_ttl                = 0
-    default_ttl            = 604800   # 7 days
+    default_ttl            = 604800  # 7 days
     max_ttl                = 31536000 # 1 year
     compress               = true
+
+    # Associate CloudFront Function for URL rewriting
+    function_association {
+      event_type   = "viewer-request"
+      function_arn = aws_cloudfront_function.url_rewrite.arn
+    }
   }
 
   # Custom error responses for SPA-like behavior
