ice/README.md

Great Lakes Ice Report

A community-driven web application for tracking winter road conditions and icy hazards in the Great Lakes region. Reports automatically expire after 48 hours to maintain current information.

Features

• 🗺️ Interactive Map - Real-time location tracking centered on Grand Rapids
• ⚡ Fast Geocoding - Lightning-fast address lookup with MapBox API
• 🔄 Auto-Expiration - Reports automatically removed after 24 hours
• 👨‍💼 Admin Panel - Manage and moderate location reports
• 📱 Responsive Design - Works on desktop and mobile devices
• 🔒 Privacy-Focused - No user tracking, community safety oriented

Quick Start

Prerequisites

• Node.js 18+
• MapBox API token (free tier available)

Local Development

1. Clone the repository:

   git clone git@github.com:deco/ice.git
   cd ice
   

2. Install dependencies:

   npm install
   

   Note: CSS is automatically built via the postinstall script

3. Configure environment variables:

   cp .env.example .env
   # Edit .env with your MapBox token
   

4. Start the server:

   npm start          # Production mode
   npm run dev        # Development mode
   npm run dev-with-css  # Development with CSS watching
   

5. Visit the application:

   http://localhost:3000
   

CSS Development

This project uses SCSS for styling. The CSS is generated and should not be committed to git.

• Build CSS once: npm run build-css
• Build CSS (dev mode): npm run build-css:dev
• Watch CSS changes: npm run watch-css
• Dev with CSS watching: npm run dev-with-css

SCSS files are organized in src/scss/:

• main.scss - Main entry point
• _variables.scss - Theme variables and colors
• _mixins.scss - Reusable SCSS mixins
• pages/ - Page-specific styles
• components/ - Component-specific styles

Environment Variables

# Required for fast geocoding
MAPBOX_ACCESS_TOKEN=pk.your_mapbox_token_here

# Admin panel access
ADMIN_PASSWORD=your_secure_password

# Server configuration
PORT=3000

Deployment

Automated Deployment (Debian 12 ARM64)

1. Run the deployment script on your server:

   curl -sSL https://ice-puremichigan-lol.s3.amazonaws.com/scripts/deploy.sh | bash
   

2. Deploy your application:

   git clone git@github.com:deco/ice.git /opt/ice
   cd /opt/ice
   npm install  # This automatically builds CSS via postinstall
   

3. Configure environment:

   cp .env.example .env
   nano .env  # Add your API keys
   

4. Start services:

   sudo systemctl enable ice
   sudo systemctl start ice
   sudo systemctl enable caddy
   sudo systemctl start caddy
   

Manual Deployment

See docs/deployment.md for detailed manual deployment instructions.

API Endpoints

• GET /api/locations - Get active location reports
• POST /api/locations - Submit new location report
• GET /api/config - Get API configuration
• GET /admin - Admin panel (password protected)

Technology Stack

• Backend: Node.js, Express.js, SQLite
• Frontend: Vanilla JavaScript, Leaflet.js
• Geocoding: MapBox API (with Nominatim fallback)
• Reverse Proxy: Caddy (automatic HTTPS)
• Database: SQLite (lightweight, serverless)

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Security

• API keys are stored in environment variables
• Admin routes are password protected
• Database queries use parameterized statements
• HTTPS enforced in production

License

MIT License - see LICENSE file for details

Support

This is a community safety tool. For issues or questions:

• Create a GitHub issue
• Check existing documentation
• Review security guidelines

---

⚠️ Safety Notice: This tool is for community awareness. Always prioritize personal safety and know your rights.