Skip to content
BSWEN
Blog

How to Set Up World Monitor: A Zero-Config Intelligence Dashboard

Cowrie
Cowrie
Dev @ Bswen

The Problem: Setting Up a Global Intelligence Dashboard

I wanted a self-hosted dashboard to monitor global events - stocks, geopolitical events, aircraft tracking, and more. I discovered World Monitor, but documentation was scattered. I needed a clear setup guide that covered both basic installation and the optional API configurations for full functionality.

Environment

  • Node.js: 18+
  • Go: 1.21+ (for proto generation)
  • OS: macOS / Windows / Linux

What Happened During Setup

First Attempt: Basic Clone and Run

I cloned the repository and tried to run it:

terminal
git clone https://github.com/koala73/worldmonitor.git
cd worldmonitor
npm install
npm run dev

The development server started immediately:

terminal output
  VITE v5.0.0  ready in 342 ms


  ➜  Local:   http://localhost:5173/
  ➜  Network: http://192.168.1.100:5173/

I opened http://localhost:5173 and the dashboard loaded. No environment variables required. The map displayed with multiple data layers visible.

Second Attempt: Using Make for Full Setup

I noticed a Makefile in the repository and wanted to understand what additional setup it provided:

terminal
make install

This command installed:

  • buf (Protocol Buffers linter and generator)
  • protobuf plugins
  • npm dependencies
  • proto dependencies

The make install approach is recommended for development work because it ensures all proto generation tools are available.

Solution: Complete Setup Guide

Step 1: Clone and Install Dependencies

terminal
git clone https://github.com/koala73/worldmonitor.git
cd worldmonitor
make install   # Full setup with proto tools
npm run dev    # Start development server

If you don’t have make available, use:

terminal
npm install
npm run dev

Step 2: Access the Dashboard

Open your browser to http://localhost:5173. The dashboard loads with all default data layers.

Step 3: Configure Optional API Keys (Optional)

The dashboard works without any configuration. Some data layers require API keys to display their data:

VariableServiceWhat It Enables
FINNHUB_API_KEYFinnhubReal-time stock quotes
EIA_API_KEYEIAOil and energy analytics
CLOUDFLARE_API_TOKENCloudflareInternet outage detection
ACLED_ACCESS_TOKENACLEDProtest and conflict data
OPENSKY_CLIENT_IDOpenSkyMilitary aircraft tracking
OPENSKY_CLIENT_SECRETOpenSkyMilitary aircraft tracking

Create a .env file based on .env.example:

terminal
cp .env.example .env

Then edit .env and add your keys:

.env
FINNHUB_API_KEY=your_finnhub_key_here
EIA_API_KEY=your_eia_key_here

Step 4: Explore Variants

World Monitor supports multiple variants for different use cases. Change the VITE_VARIANT environment variable:

terminal
# Full geopolitical monitoring
VITE_VARIANT=full npm run dev


# Technology sector focus
npm run dev:tech


# Financial markets focus
npm run dev:finance


# Commodity tracking
npm run dev:commodity


# Positive news only
npm run dev:happy

Step 5: Desktop App Installation (Alternative)

If you prefer a native desktop app, download pre-built binaries:

  • Windows: .exe installer
  • macOS: Apple Silicon or Intel builds
  • Linux: .AppImage file

The desktop app provides additional features:

  • Access settings with Cmd+, (macOS) or Ctrl+, (Windows/Linux)
  • Configure LLM endpoints for AI analysis
  • Enable traffic logging for debugging

Why This Works

World Monitor uses Vite’s environment variable system (VITE_* prefix) to configure variants and API endpoints. The zero-config default works because:

  1. The frontend loads with hardcoded fallback values
  2. Optional API layers gracefully degrade when keys are missing
  3. Variant selection is purely client-side routing and configuration

The make install command ensures Protocol Buffers tooling is available, which is needed if you’re modifying the data schemas or contributing to the project.

Keyboard Shortcuts

  • Cmd+K / Ctrl+K - Open search
  • Up/Down - Navigate search results
  • Esc - Close modals

Map Controls

  • Mouse wheel or trackpad pinch to zoom
  • Click and drag to pan
  • Layer toggle buttons in the sidebar for 20+ data layers

Panel Management

  • Drag panels to reorder
  • Toggle visibility in Settings
  • Collapsed panels continue refreshing data in the background

Deployment Options

World Monitor supports multiple deployment targets:

Vercel Edge Functions:

terminal
npm run build
vercel deploy

Docker:

terminal
docker build -t worldmonitor .
docker run -p 5173:5173 worldmonitor

Static Site:

terminal
npm run build
# Deploy the dist/ folder to any static host

Summary

In this post, I showed how to set up World Monitor from clone to running dashboard. The key insight is that basic operation requires zero configuration - just npm install && npm run dev. Optional API keys unlock additional data layers, and variant selection lets you customize the dashboard focus. The project also offers desktop apps and multiple deployment options for production use.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: