Queen of San Diego — Tech Blog

Under the hood at queenofsandiego.com

```html

Publishing Charter Documents to CloudFront: S3 Integration and Live URL Verification for JADA Operations

What Was Done

This session focused on establishing a reliable document publishing pipeline for JADA charter operations, specifically implementing S3 storage and CloudFront distribution for dynamically generated charter manifests and trip sheets. The core objective was to take locally-generated HTML documents (Quinn Male charter manifest and trip sheet) and publish them to S3, then verify they're accessible via CloudFront URLs with proper HTTP 200 responses.

The workflow involved:

  • Generating charter documents in /tmp/quinn-male-manifest.html and /tmp/quinn-male-trip-sheet.html
  • Publishing both documents to an S3 bucket used by the shipcaptaincrew project
  • Verifying live URLs return successful responses
  • Spot-checking content integrity between local and published versions

Technical Details: Document Generation and Format

The charter documents were generated as self-contained HTML files following the shipcaptaincrew project's template structure. Each document includes:

  • Manifest: Passenger list, safety information, departure/arrival times, crew assignments
  • Trip Sheet: Detailed itinerary, meal schedules, activity timings, emergency procedures

Rather than storing these in the local repository (which would bloat version control), they were generated on-demand and published directly to S3. This pattern allows the document generation logic to live in the codebase while keeping the published artifacts in cloud storage—a cleaner separation of concerns than committing HTML artifacts to git.

The documents were extracted from reference charter pages found in the shipcaptaincrew project, specifically examining existing charter documents like the McLaughlin manifest to understand the expected format and structure.

Infrastructure: S3 and CloudFront Configuration

The shipcaptaincrew project uses an S3 bucket for document storage with CloudFront distribution for edge caching and HTTPS delivery. Key infrastructure components:

  • S3 Bucket: Dedicated bucket within the shipcaptaincrew project's AWS account, organized with a /docs prefix for published documents
  • CloudFront Distribution: Configured to serve content from the S3 bucket with edge caching enabled
  • Document Path Structure: s3://[bucket]/docs/charters/[captain-name]/[document-type].html

The CloudFront distribution provides several advantages over direct S3 access:

  • HTTPS termination: All clients connect via HTTPS to edge locations
  • Geographic distribution: Content cached at 200+ edge locations globally (though JADA charters are local, this provides high availability)
  • Reduced S3 costs: Edge caching prevents repeated S3 GetObject calls
  • DDoS protection: AWS Shield and WAF can be applied at the CloudFront layer

Publishing Pipeline and AWS Authentication

The publishing workflow required proper AWS credential management. The session encountered and resolved an authentication challenge:

# Initial attempt to publish documents
# Received AWS authentication errors when credentials expired

# Solution: Re-authenticate the AWS session
aws sts get-caller-identity  # Verify auth status

# Publish documents after successful authentication
aws s3 cp /tmp/quinn-male-manifest.html s3://[bucket]/docs/charters/quinn-male/manifest.html
aws s3 cp /tmp/quinn-male-trip-sheet.html s3://[bucket]/docs/charters/quinn-male/trip-sheet.html

Rather than embedding credentials in scripts, the approach uses AWS credential chain resolution: IAM roles for EC2 (if applicable), environment variables set via secure credential providers, or local AWS CLI configuration in ~/.aws/credentials. This follows the principle of least privilege—credentials have minimal required permissions (S3 PutObject for specific paths only).

Verification and Content Integrity

After publishing, verification occurred at two levels:

  • HTTP status verification: CloudFront URLs were tested to confirm HTTP 200 responses: 
    curl -I https://[cloudfront-domain]/docs/charters/quinn-male/manifest.html
# Expected: HTTP/2 200 OK
# Headers include: x-amz-cf-pop (CloudFront POP), x-amz-cf-id (request ID)
  • Content spot-check: Local file checksums compared against served content to ensure no corruption during S3 upload
  • File existence verification: Confirmed both documents still existed in /tmp and in S3 before marking the task complete

Key Decisions and Rationale

Why S3 + CloudFront instead of filesystem storage? JADA operations may need to serve documents to crew members and clients from multiple geographic locations. S3 provides durable, redundant storage; CloudFront provides global distribution and HTTPS. This scales better than serving from a single origin server.

Why generate documents in /tmp rather than the repository? Charter documents are generated dynamically based on calendar data and trip details. Storing them in git would create merge conflicts and bloat the repository. Generating on-demand and publishing to S3 keeps the repository lean while maintaining archival capability (S3 versioning can be enabled).

Why verify both HTTP status and content? CloudFront can serve stale content from cache if an S3 object exists. Verifying the actual served content ensures the published version matches what was intended, catching potential issues with S3 permissions, CloudFront invalidation, or cache TTL misconfiguration.

Session Artifacts and Documentation

The session generated several documentation files:

  • /Users/cb/Documents/repos/jada-ops/weekend-charters-readiness-2026-05-29.md: Comprehensive charter readiness report for weekend operations
  • /Users/cb/Documents/repos/agent_handoffs/projects/quinn-male-charter.md: Charter-specific handoff documentation with payment details and crew assignments

These markdown files serve as operational records and can be version-controlled without the bulk of binary or large HTML artifacts.

What's Next

The immediate next steps for charter operations:

  • Extend the publishing pipeline to generate and publish documents for all weekend charters (currently focused on Quinn Male)
  • Implement an automated S3 cleanup process to archive published documents older than 90 days (reduces S3 storage costs)
  • Configure CloudFront cache invalidation on document publication to ensure crew receives fresh manifests
  • Add SMS notification delivery to crew members with CloudFront URLs (leveraging shipcaptaincrew SMS utility tools)

This establishes the foundational infrastructure for reliable document distribution across JADA's charter operations.

```