Setup & Installation

This guide covers how to clone the repository and set up your local development environment.

Prerequisites

• Git - Version control
• Python 3.8+ - For local development server and MkDocs
• Modern web browser - Chrome, Firefox, Safari, or Edge

Clone the Repository

# Clone via HTTPS
git clone https://github.com/tswetnam/m580-2026.git

# Or clone via SSH
git clone git@github.com:tswetnam/m580-2026.git

# Navigate to the project directory
cd m580-2026

Project Structure

m580-2026/
├── index.html              # MapLibre version (requires WebGL)
├── index-leaflet.html      # Leaflet version (Canvas rendering)
├── css/
│   └── style.css           # Shared styles
├── js/
│   ├── app.js              # MapLibre JavaScript
│   └── app-leaflet.js      # Leaflet JavaScript
├── data/
│   ├── units.geojson       # Polygon boundaries (1.6 MB)
│   └── offices.geojson     # Point locations
├── docs/                   # MkDocs documentation
├── mkdocs.yml              # MkDocs configuration
└── README.md

Running Locally

Option 1: Python HTTP Server

# Start server on port 8080
python3 -m http.server 8080

# Or specify a different port
python3 -m http.server 3000

Then open in your browser:

• Leaflet version: http://localhost:8080/index-leaflet.html
• MapLibre version: http://localhost:8080/index.html

Option 2: VS Code Live Server

1. Install the "Live Server" extension
2. Right-click on index-leaflet.html
3. Select "Open with Live Server"

Option 3: Node.js (if installed)

npx serve .

Installing MkDocs

To build and preview the documentation locally:

# Install MkDocs and Material theme
pip install mkdocs mkdocs-material mkdocs-minify-plugin

# Serve documentation locally
mkdocs serve

# Build static documentation
mkdocs build

The documentation will be available at http://localhost:8000.

Environment Notes

Remote VM / No GPU

If running on a remote VM without GPU support, use the Leaflet version (index-leaflet.html). The MapLibre version requires WebGL which may not work without hardware acceleration.

Browser Compatibility

Troubleshooting

Port Already in Use

# Find process using the port
lsof -i :8080

# Use a different port
python3 -m http.server 8082

WebGL Errors

If you see "Failed to initialize WebGL" errors:

1. Use index-leaflet.html instead
2. Or try Chrome with: chrome --ignore-gpu-blocklist
3. Or enable hardware acceleration in browser settings