Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

Deploying a Receipt Management System for quickdumpnow.com: S3, CloudFront, and Custom Error Handling

This post documents the deployment of a new receipt management interface for quickdumpnow.com's trailer rental business operations. The work involved creating a dedicated `/books` endpoint, configuring S3 object storage with dual-key deployment patterns, and troubleshooting CloudFront's custom error responses that were masking the new page behind the homepage.

Problem Statement

quickdumpnow.com needed a dedicated page at https://quickdumpnow.com/books to serve as a receipt collection point for trailer rental transactions. The development team had created the page locally at /Users/cb/Documents/repos/sites/quickdumpnow.com/books/index.html, but deployment to production was returning the homepage instead of the new books page—a classic CDN caching and origin configuration issue.

Technical Implementation

Local File Structure and Development

The project maintained the following directory structure:

/Users/cb/Documents/repos/sites/quickdumpnow.com/
├── books/
│   └── index.html          # New receipt management page
├── robots.txt              # Updated to exclude /books
└── [other site assets]

The books/index.html page was built following the existing quickdumpnow.com design patterns and styling to maintain visual consistency across the site. The page functionality is specifically designed to allow users to upload and track receipt documentation for trailer rental transactions.

S3 Deployment Strategy: Dual-Key Pattern

One of the key decisions made during deployment was to upload the books page using two distinct S3 object keys. This pattern addresses a subtle but important issue with how CloudFront and browsers handle directory-style URLs:

  • Object key 1: books/index.html — The literal file path as it exists in the repository. This handles requests where users or tools explicitly request the index file.
  • Object key 2: books — A bare key (no extension) containing the same HTML content. This enables "pretty URLs" where a request to /books (without trailing slash) directly resolves to the content without requiring a 301/302 redirect or CloudFront index document configuration.

The upload commands executed (with sensitive S3 credentials redacted) were:

# Upload with explicit index.html key
aws s3 cp books/index.html s3://[bucket-name]/books/index.html \
  --content-type "text/html; charset=utf-8" \
  --cache-control "max-age=3600"

# Upload with bare 'books' key for direct URL matching
aws s3 cp books/index.html s3://[bucket-name]/books \
  --content-type "text/html; charset=utf-8" \
  --cache-control "max-age=3600"

Why this approach? Without the bare books key, a request to https://quickdumpnow.com/books would fail if CloudFront wasn't configured with index document rewriting, or it would trigger a redirect—degrading the user experience. By uploading to both keys, we ensure maximum compatibility across different request patterns.

robots.txt Updates

The robots.txt file was updated to exclude search engine indexing of the new books page. This is intentional—the receipt management interface should not appear in search results. The updated file was deployed with the same S3 and CloudFront invalidation commands as the books page.

CloudFront Invalidation and Caching

After uploading to S3, CloudFront cache invalidations were triggered for both request patterns:

aws cloudfront create-invalidation \
  --distribution-id [DIST_ID] \
  --paths "/books" "/books/*" "/robots.txt"

The invalidation request targeted:

  • /books — The bare path (matches the dual-key S3 upload strategy)
  • /books/* — Any sub-paths under books (for future expansion)
  • /robots.txt — Updated robots rules

CloudFront's invalidation propagates across all edge locations within 30-60 seconds, ensuring the new content is available globally without waiting for default TTL expiration (which was configured to 1 hour via max-age=3600).

Infrastructure Diagnosis: CloudFront Custom Error Responses

Initial deployment testing showed that requests to https://quickdumpnow.com/books were returning the site's homepage rather than the new books page. This indicated a CloudFront configuration issue, not an S3 problem.

Investigation revealed that the CloudFront distribution had a custom error response configured:

  • Error code: 404 (Not Found)
  • Error caching TTL: Default (300 seconds)
  • Response page path: Root homepage (likely /index.html or /)

This configuration, while useful for gracefully handling missing pages, was too broad. Any request that returned a 404 from the origin—including the initial request to /books before S3 object creation—would be masked by the homepage redirect. Once the S3 objects were created, the 404 error responses ceased, but the diagnosis process was valuable for understanding the distribution's behavior.

Origin Configuration

The CloudFront distribution was configured with:

  • Origin type: S3 bucket (origin domain: [bucket-name].s3.amazonaws.com)
  • Origin path: Empty (all requests pass directly to S3 root)
  • S3 access: Origin Access Control (OAC) restricting direct S3 access to CloudFront only
  • Default root object: Not set at distribution level (relies on S3 index document or dual-key strategy)

The OAC configuration ensures that the S3 bucket is not exposed publicly—all traffic flows through CloudFront, allowing for caching, WAF integration, and access logging.

Key Architectural Decisions

  • Dual-key S3 uploads: Eliminates complexity around URL rewriting and ensures the pretty URL /books works without redirects or additional CloudFront configuration.
  • Per-object cache headers: Setting max-age=3600 (1 hour) balances freshness for dynamic receipt data against edge location efficiency. If more frequent updates are needed, this can be reduced or set to max-age=0 with must-revalidate.
  • Broad CloudFront invalidation patterns: Using /books/* ensures future additions to the books directory (e.g., /books/history, /books/api) are invalidated preemptively.
  • Robots.txt exclusion: Prevents SEO indexing of internal business tools, keeping the site's search footprint clean.

What's Next

The books page is now live and accessible at https://quickdumpnow