WeatherForge

A real-time weather dashboard with environmental monitoring
Report Bug · Request Feature

Table of Contents

1. About The Project
   • Key Features
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Deployment
6. Contributing
7. License
8. Contact
9. Acknowledgments

About The Project

WeatherForge is a Rails 8.1+ advanced real-time weather dashboard that integrates multiple Open Meteo APIs and OpenAQ API v3 to provide comprehensive weather data, forecasts, marine conditions, air quality, flood risk information, and environmental monitoring with live updates using Hotwire (Turbo + Stimulus).

Key Features

Weather Monitoring:

• Real-time weather data with automatic 5-minute updates via background jobs
• Interactive Chartkick charts for temperature, humidity, and wind speed trends
• 24-hour forecasts and 10-day historical weather data
• Marine weather conditions (wave height, period, water temperature)
• Air quality monitoring (PM2.5, PM10, O3, NO2, SO2) with AQI levels
• Flood risk assessment with severity indicators
• Location search with geocoding via Open Meteo API
• Turbo Streams for real-time updates without polling

Environmental Monitoring (GIS Extension):

• Real-time air quality sensor network with OpenAQ API v3 integration
• Interactive Leaflet.js maps with sensor markers and clustering
• PostgreSQL/PostGIS spatial queries for nearby sensors (ST_DWithin)
• Automated threshold alerts (PM2.5, PM10, O3, NO2, SO2, CO)
• Health level indicators (Good, Moderate, Unhealthy for Sensitive Groups, Unhealthy, Very Unhealthy, Hazardous)
• Time-series charts for 24-hour environmental readings
• GeoJSON API endpoints for custom map integrations
• Alert resolution tracking with timestamps and notes

Weather Dashboard	Weather Trends

Weather Forecasts	Environmental Data

Sensors Dashboard	Environmental Alerts

Alert Details	Sensor Details

(back to top)

Built With

• 
• 
• 
• 
• 

(back to top)

Getting Started

Prerequisites

• Ruby 3.4+

  ruby --version

• Node.js 22+

  node --version

• Docker & Docker Compose (for PostgreSQL with PostGIS and Redis)

  docker --version
  docker compose version

Installation

Option 1: Docker (Recommended for Quick Setup)

1. Clone the repo

   git clone https://github.com/vijethph/WeatherForge.git
   cd WeatherForge

2. Run setup script

   bin/docker-setup

   The script will configure your environment automatically. Alternatively, manually set up:

   cp .env.example .env
   # Get your user ID and group ID
   id -u  # Add to USER_ID in .env
   id -g  # Add to GROUP_ID in .env
   # Add your master key to RAILS_MASTER_KEY in .env

3. Build and start all services

   docker compose build
   docker compose up -d

4. Check logs

   docker compose logs -f web

5. Visit http://localhost:3000

Docker Commands:

# View all logs
docker compose logs -f

# Rails console
docker compose exec web bin/rails console

# Run migrations
docker compose exec web bin/rails db:migrate

# Stop services
docker compose down

# Clean restart
docker compose down -v && docker compose up -d --build

Option 2: Local Development

1. Clone the repo

   git clone https://github.com/vijethph/WeatherForge.git
   cd WeatherForge

2. Install dependencies

   bundle install
   npm install

3. Setup environment variables

   cp .env.example .env
   # Edit .env with your actual values (PostgreSQL credentials, OpenAQ API key, etc.)

4. Start database and Redis services

   docker compose up -d postgres redis

5. Setup database (creates and migrates with PostGIS extension)

   rails db:setup

6. Start the server (starts Rails + JS build watcher)

   bin/dev

7. Start Sidekiq (in separate terminal)

   bundle exec sidekiq

8. Visit http://localhost:3000

Additional URLs:

• API Docs: http://localhost:3000/api-docs
• Sidekiq Dashboard: http://localhost:3000/sidekiq

(back to top)

Usage

Dashboard Pages

• / - Main dashboard with current weather for all locations
• /dashboards/trends - 24-hour temperature, humidity, wind charts
• /dashboards/forecasts - Hourly forecasts and historical data
• /dashboards/environment - Marine weather, air quality, flood risk

Managing Locations

Add Location:

1. Navigate to Locations page
2. Search for a city or enter coordinates
3. Submit to add location

Sync Weather:

• Automatic: Every 5 minutes via Sidekiq
• Manual: Click "Sync All Weather" button

API Endpoints

GET  /                              # Main dashboard
GET  /dashboards/trends             # Trends page
GET  /dashboards/forecasts          # Forecasts page
GET  /dashboards/environment        # Environment page
POST /dashboards/sync_weather       # Manual sync

GET  /locations                     # List locations
GET  /locations/search?query=city   # Search locations
POST /locations                     # Create location
DELETE /locations/:id               # Delete location

Interactive API documentation available at /api-docs.

Testing

# Run tests
bundle exec rspec

# Run with coverage
COVERAGE=true bundle exec rspec

# Code quality
bundle exec rubocop
bundle exec brakeman
bundle exec bundler-audit

(back to top)

Deployment

Render (Recommended)

The app includes render.yaml for one-click deployment with PostgreSQL and Redis.

1. Push code to GitHub
2. Connect repository to Render
3. Set RAILS_MASTER_KEY environment variable
4. Deploy automatically on push to main

Docker

# Build image
docker build -t weatherforge .

# Run with docker-compose
docker compose up

Environment Variables

Required for production:

RAILS_MASTER_KEY=your_master_key
DATABASE_URL=postgresql://user:pass@host:5432/dbname
REDIS_URL=redis://host:6379/0

(back to top)

Contributing

Contributions are welcome!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'feat: add amazing feature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the Apache License 2.0. See LICENSE for more information.

(back to top)

Contact

Vijeth P H - @vijethph

Project Link: https://github.com/vijethph/WeatherForge

(back to top)

Acknowledgements

• Open Meteo
• OpenAQ
• Chartkick
• Bootstrap
• Leaflet.js
• Sidekiq
• PostgreSQL
• PostGIS

(back to top)