How to Deploy & Use World Monitor

# World Monitor Deployment & Usage Guide

## 1. Prerequisites

| Requirement | Version | Purpose |
|-------------|---------|---------|
| **Node.js** | 18.x LTS or higher | Runtime for Vite build system and TypeScript compilation |
| **npm** | 9.x or higher | Package management (yarn/pnpm also supported) |
| **Git** | 2.30+ | Source control |
| **Rust** (optional) | 1.70+ | Required only for building Tauri desktop apps |
| **Ollama** (optional) | Latest | Local LLM support for AI-synthesized briefs without API keys |

### System Requirements
- **RAM**: 4GB minimum (8GB recommended for development with local AI)
- **Storage**: 2GB free space (excluding local AI models)
- **Browser**: Chrome 90+, Firefox 88+, Safari 14+, or Edge 90+ (WebGL 2.0 required for 3D globe)

## 2. Installation

```bash
# Clone the repository
git clone https://github.com/koala73/worldmonitor.git
cd worldmonitor

# Install dependencies
npm install

# Verify installation
npm run type-check

3. Configuration

Create environment files in the project root:

Base Configuration (.env)

# Site Variant: 'full' | 'tech' | 'finance'
VITE_SITE_VARIANT=full

# Enable E2E testing mode (optional)
VITE_E2E=0

# API Configuration for external data sources
VITE_NEWS_API_KEY=your_newsapi_key_here
VITE_MAPTILER_KEY=your_maptiler_key_here

# Local AI Configuration (optional)
VITE_OLLAMA_URL=http://localhost:11434
VITE_OLLAMA_MODEL=llama3.1

# Feature flags
VITE_ENABLE_MILITARY_TRACKING=true
VITE_ENABLE_OFFLINE_MAPS=true

Variant-Specific Builds

The application supports three deployment variants from a single codebase:

Data Source Configuration

Edit src/config/bases-expanded.ts to update military base statuses or add new intelligence data points. The file uses TypeScript types for type safety:

// Example: Adding a new monitoring location
{
  id: 'custom_base',
  name: 'Custom Monitoring Station',
  lat: 51.5074,
  lon: -0.1278,
  type: 'custom',
  country: 'United Kingdom',
  arm: 'Intelligence',
  status: 'active',
  description: 'Custom intelligence gathering point'
}

4. Build & Run

Development Server

# Run default variant (World Monitor)
npm run dev

# Run specific variant
VITE_SITE_VARIANT=tech npm run dev

# Run with local AI enabled
VITE_OLLAMA_URL=http://localhost:11434 npm run dev

The dev server starts at http://localhost:5173 by default.

Production Build

# Build for production (includes Brotli compression)
npm run build

# Build specific variant
VITE_SITE_VARIANT=finance npm run build

# Preview production build locally
npm run preview

Desktop App (Tauri)

# Ensure Rust is installed: https://rustup.rs/
# Install Tauri CLI
npm install -g @tauri-apps/cli

# Build desktop app for current platform
npm run tauri build

# Build for specific targets
npm run tauri build -- --target x86_64-pc-windows-msvc
npm run tauri build -- --target x86_64-apple-darwin
npm run tauri build -- --target aarch64-apple-darwin
npm run tauri build -- --target x86_64-unknown-linux-gnu

PWA Build

The Progressive Web App is automatically built via vite-plugin-pwa. The build generates:

• Service worker for offline functionality
• Offline map tile caching
• Installable manifest (configured per variant in vite.config.ts)

5. Deployment

Static Web Hosting (Recommended)

Deploy the dist/ folder contents to any static host:

Vercel

npm i -g vercel
vercel --prod

Cloudflare Pages

npm run build
npx wrangler pages deploy dist

Netlify

npm run build
netlify deploy --prod --dir=dist

Docker Deployment

# Dockerfile
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80

docker build -t worldmonitor .
docker run -p 8080:80 worldmonitor

Environment-Specific Notes

With Local AI (Ollama) If deploying with local AI support:

1. Install Ollama on the server: curl -fsSL https://ollama.com/install.sh | sh
2. Pull required model: ollama pull llama3.1
3. Set VITE_OLLAMA_URL to the server address (use reverse proxy for HTTPS)
4. Ensure CORS is configured in Ollama: OLLAMA_ORIGINS=https://yourdomain.com ollama serve

Offline Map Support For full offline functionality:

1. Pre-download map tiles to public/tiles/
2. Update src/config/map-config.ts to point to local tile source
3. Ensure VITE_ENABLE_OFFLINE_MAPS=true is set

6. Troubleshooting

Build Issues

Error: Cannot find module '@/types'

• Ensure TypeScript path aliases are configured in tsconfig.json
• Run npm run type-check to verify imports

Error: VitePWA is not a function

• Delete node_modules and lock file
• Run npm install again

Brotli compression fails

• Node.js zlib limitation on Windows: Install Visual Studio Build Tools or disable plugin in vite.config.ts

Runtime Issues

Blank map / WebGL errors

• Verify WebGL 2.0 support: Visit https://get.webgl.org/webgl2/
• Check browser console for CORS errors on map tiles
• Ensure VITE_MAPTILER_KEY is valid (if using MapTiler)

News feeds not loading

• Check browser Network tab for CORS errors
• If self-hosting, configure proxy in vite.config.ts:

server: {
  proxy: {
    '/api/news': {
      target: 'https://news-source.com',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api\/news/, '')
    }
  }
}

AI features unavailable

• Verify Ollama is running: curl http://localhost:11434/api/tags
• Check browser console for CORS errors
• Ensure model is downloaded: ollama list

Variant switching not working

• Clear browser localStorage (variant preference cached)
• Check that VITE_SITE_VARIANT is set at build time, not runtime
• For dynamic switching, use the UI header bar (🌍 WORLD | 💻 TECH | 📈 FINANCE)

Performance Issues

High memory usage

• Disable unnecessary map layers in the UI
• Reduce maxClusters in src/config/map-limits.ts
• For development, disable Brotli compression to speed up builds

Slow initial load

• Enable lazy loading for language bundles (default behavior)
• Use npm run build -- --mode production for optimized assets
• Verify Brotli precompression is working (check for .br files in dist/)

Data Accuracy

Outdated military base status

• Edit src/config/bases-expanded.ts directly
• Follow existing comment format for status updates
• Submit PR with source citations for permanent fixes

Missing translations

• Add language files to src/locales/
• Update src/i18n/config.ts to register new language
• RTL languages require dir="rtl" in HTML template