🌦️ Weather Site

📖 Description

Inspired by isitsnowinginpdx.com ❄️
See blog post for more details 📝

A serverless weather reporting website that answers a single question: "Is it [condition] in [location]?" with a simple YES/NO response 🎯

This automated workflow:

1. 📍 Gets the current website status for a specified location
2. 🌤️ Hits the OpenWeatherMap API to get current weather conditions
3. 🔄 If the status has changed → updates the website with new weather conditions
4. ⏰ Runs automatically on a schedule via EventBridge Scheduler

My deployment of this site is here 🚀

🔴 When the weather is happening (YES!):

🟢 When the weather is NOT happening (Nope!):

🏗️ Architecture

🎯 Core Stack (Always Required)

• 🪣 S3 - Static website hosting
• 🌐 CloudFront - Global CDN distribution
• ⚡ Lambda - HTML generation and site updates (ARM64)
• 🔄 Step Functions - Orchestrates weather checks and updates
• ⏰ EventBridge Scheduler - Triggers checks every 10 minutes
• 📊 Systems Manager Parameter Store - Stores current site status
• 🔐 Secrets Manager - Stores OpenWeatherMap API key
• 👀 CloudWatch - Alarm for monitoring Step Function failures
• 📧 SNS - Optional email notifications (only when ALERT_EMAIL is configured)

🌍 Optional Custom Domain Stack

• 🌐 Route53 - DNS hosted zone management
• 🔒 Certificate Manager - SSL certificates for HTTPS
• ↩️ CloudFront Function - www → non-www redirects

🛠️ Technologies

• 🟢 Runtime: Node.js (version in .nvmrc)
• 📘 Language: TypeScript with strict configuration
• 🏗️ Infrastructure: AWS CDK v2 for Infrastructure as Code
• 🌤️ API: OpenWeatherMap One Call API 3.0

🔄 Step Function State Machine

🚀 Deployment Options

🎯 Basic Deployment (CloudFront Default Domain)

Works out of the box with a CloudFront-generated domain (e.g., d123456789.cloudfront.net) ✨

🌍 Custom Domain Deployment

Requires additional domain stack deployed to us-east-1 region for SSL certificates 🔒

📋 Setup Instructions

✅ Prerequisites

1. 🟢 Install Node.js (see .nvmrc for required version)
2. ☁️ Install AWS CLI and configure credentials
3. 🔑 Get an API key from OpenWeatherMap

🛠️ Basic Setup

1. 📥 Clone the repository

2. 🔐 Create a Secret in AWS Secrets Manager:

   • Name: weather-site-api-key
   • Value: Your OpenWeatherMap API key (plaintext)

3. ⚙️ Copy .env.example to .env and configure:

   cp .env.example .env

   • Set required variables: WEATHER_LOCATION_LAT, WEATHER_LOCATION_LON, LOCATION_NAME, etc.
   • Optionally set ALERT_EMAIL for email notifications when site status changes or system failures occur 📧
   • Leave DOMAIN_NAME empty for basic deployment

4. 📦 Install dependencies:

   npm install

5. 👤 Set AWS profile (optional):

   export AWS_PROFILE=<your_aws_profile>

🚀 Deployment Commands

🎯 Basic Deployment (No Custom Domain)

npm run deploy

The CloudFront URL will be output to the console 📋

🌍 Custom Domain Deployment

⚠️ Important: Domain stack must be deployed to us-east-1 region first!

1. 📝 Set DOMAIN_NAME in your .env file
2. 🌐 Deploy domain stack to us-east-1:

   npm run deploy -- --region us-east-1 --exclusively "*-domain"

3. ☁️ Deploy weather stack to your preferred region:

   npm run deploy -- --region us-west-2 --exclusively "*-weather"

🌍 Custom Domain Setup

🌐 DNS Requirements

• If your domain is not hosted in Route53, point your nameservers to Route53 (instructions) 🔄
• For non-Route53 domains: Update nameservers quickly after domain stack deployment starts to prevent certificate validation failures ⚡

🗺️ Regional Requirements

• 🌐 Domain Stack: Must deploy to us-east-1 (CloudFront SSL certificate requirement) 🔒
• ☁️ Weather Stack: Can deploy to any AWS region 🌎

🎁 What Gets Created

• 🌐 Route53 hosted zone for your domain
• 🔒 SSL certificates for both example.com and www.example.com
• ☁️ CloudFront distribution with custom domain
• ↩️ Automatic www → non-www redirect
• 📍 DNS A records pointing to CloudFront

⏱️ Certificate Validation

• 🕐 DNS validation can take up to 30 minutes
• 👀 Monitor AWS Console for certificate status
• ⚡ Ensure nameservers are updated promptly for external domains

🌎 Multi-Region Deployment Pattern

# Step 1: 🌐 Deploy domain resources (us-east-1 required)
npm run deploy -- --region us-east-1 --exclusively "myStack-domain"

# Step 2: ☁️ Deploy main application (any region)
npm run deploy -- --region us-west-2 --exclusively "myStack-weather"

👨‍💻 Development

🛠️ Available Commands

npm run build          # 🔨 Compile TypeScript
npm run test           # 🧪 Run Jest tests
npm run format         # ✨ Format code with Prettier
npm run lint           # 🔍 Lint code with ESLint
npm run synth          # 📄 Generate CloudFormation templates
npm run diff           # 👀 Preview infrastructure changes
npm run deploy         # 🚀 Interactive deployment
npm run deploy:ci      # 🤖 CI/CD deployment (no prompts)
npm run destroy        # 💥 Delete all stacks

⚙️ Environment Variables

Configure in .env file:

• 📍 WEATHER_LOCATION_LAT / WEATHER_LOCATION_LON - Coordinates for weather checks
• 🏷️ LOCATION_NAME - Display name for the location
• 🌦️ WEATHER_TYPE - Condition to check (snow, rain, etc.)
• ⏰ SCHEDULES - Cron expressions for check frequency
• 🏷️ STACK_PREFIX - Prefix for all AWS resources
• 🌐 DOMAIN_NAME - Optional custom domain
• 📧 ALERT_EMAIL - Optional email for notifications when site status changes or system failures occur

🧪 Testing

Basic CDK snapshot tests are in the test/ folder:

npm run test

📧 Email Notifications (Optional)

The weather site supports optional email notifications for two scenarios:

🔄 Status Change Notifications

When the weather condition status changes (e.g., from "NO" to "YES" or vice versa), you'll receive an email notification with the new status.

⚠️ System Failure Alerts

If the Step Function fails (e.g., API errors, deployment issues), you'll receive CloudWatch alarm notifications.

🛠️ Setup

1. Add your email address to the .env file:

   ALERT_EMAIL=your-email@example.com

2. Deploy the app:

   npm run deploy

   Or deploy the weather stack separately:

   npm run cdk deploy -- --exclusively "*-weather"

3. Important: You will receive one confirmation email from AWS SNS that you must confirm by clicking the link. This single topic handles both status change notifications and system failure alerts.

📊 What Gets Created

• 📧 SNS Topic - Handles email delivery (only when ALERT_EMAIL is set)
• 👀 CloudWatch Alarm - Monitors Step Function failures (always created, alarm action only when ALERT_EMAIL is set)
• 📬 Email Subscription - Sends notifications to your specified email

🗑️ Removing Email Notifications

To stop receiving emails:

1. Remove ALERT_EMAIL from .env
2. Redeploy the weather stack: npm run deploy

This removes the SNS topic and alarm action, stopping all email notifications. The CloudWatch alarm remains for monitoring purposes.

🧹 Cleanup

To delete all resources:

npm run destroy

🗑️ Manually delete the weather-site-api-key secret from AWS Secrets Manager.

🤝 Contributing

See CONTRIBUTING.md for more info on our guidelines.