Group Ironmen Tracker

Fork Notice: This is a heavily modified fork of christoabrown/group-ironmen with significant changes and improvements across the frontend, backend, cache tooling, and deployment infrastructure. While the core concept remains the same, much of the codebase has been rewritten or extended. See What's Changed for details.

Website	groupiron.men
RuneLite Plugin	group-ironmen-tracker

A real-time group tracking system for Old School RuneScape Group Ironman teams. A companion RuneLite plugin sends player data to a backend server, allowing all group members to view each other's stats, gear, bank, position, and more through an interactive web dashboard.

---

Contents: Screenshots · Features · What's Changed · Self-Hosting · Development · Acknowledgments · License

---

Screenshots

Click to expand screenshots

Dashboard

DPS Calculator

Banked XP

Events

Blog

Clues

Discord Integration

Item Requests	Event Notifications

Features

Dashboard

• Group Overview - Total wealth, XP gains, quest points, and collection log completion at a glance
• Member Activity - Online status, current world, and inactivity detection
• OSRS News - Latest Jagex blog posts via RSS, YouTube videos, and Twitch stream status
• Upcoming Events - Countdown banners for scheduled group events

Player Tracking

• Containers - Inventory, equipment, bank, rune pouch, seed vault, stash units, and shared bank
• Skills - All 24 skills with real-time XP drops, level progress bars, and historical graphing (day/week/month/year)
• Live Status - HP, prayer, run energy bars, current world, and combat interaction display
• World Map - Canvas-based interactive map with player markers, 6 zoom levels, 4 planes, follow mode, and NPC interaction visualization
• Quests - All quests grouped by category with per-member state tracking and quest point totals
• Achievement Diaries - 12 regions × 4 tiers with bit-packed completion tracking and individual task display
• Collection Log - 5 tabs (Bosses, Raids, Clues, Minigames, Other) with per-page completion percentages, multi-player unlock status, and wiki links
• Boss Kill Counts - Via Jagex Hiscores (Normal, Ironman, HCIM, UIM) with 5-minute cache, plus clue scroll and activity tracking

Tools & Utilities

• Banked XP Calculator - 12 skills, 500+ items, multiple activities per item, equipment modifier support (outfit bonuses), and secondary item tracking
• DPS Calculator - Full combat simulator with 35+ prayers, potion modifiers, special attacks, bolt effects, raid scaling (CoX/ToB/ToA), hit distribution histograms, and loadout saving
• Items Browser - Group-wide item aggregation with search, sort, GE/HA price display, and per-member filtering
• Grand Exchange Prices - Auto-updated every 4 hours from the OSRS Wiki API

Group Events & Discord

• Event System - 7 event types (Boss, Skilling, Minigame, Quest, Raid, PK Trip, Other) with 50+ configurable icons, event banners, and Discord webhook reminders
• Discord Integration - Rich embed event notifications with @mentions, item request messages with holder info, and per-member Discord ID linking
• OSRS Blog - Categorized news feed (Game Updates, Community, Dev Blogs, Future Updates, Events)

Group Management

• Create/Join Groups - Up to 5 members per group with optional hCaptcha verification
• Member Management - Add, rename, and remove members with cascading data cleanup
• Settings - Panel dock position, dark/light theme with system preference detection, Discord webhook configuration
• Demo Mode - Try the app with simulated XP drops, HP changes, and coordinate updates

Technical Highlights

• Unified Node.js/Express backend with batched update processing and Server-Sent Events for real-time push
• PostgreSQL with time-series skill aggregation (hourly/daily/monthly retention)
• Web Components frontend with SPA routing and responsive multi-panel layout
• OSRS cache pipeline - Automated extraction of item data, sprites, map tiles, NPC icons, and collection log structure
• Single Docker image with health checks, rate limiting, gzip compression, and auto-initialized schema

What's Changed

Key changes over the upstream repository:

• Unified architecture - Merged separate frontend/backend into a single Node.js/TypeScript application and Docker image
• TypeScript migration - Converted codebase from JavaScript to TypeScript
• Dashboard - New home page with group wealth, XP gains, quest points, collection log completion, OSRS news feed, YouTube videos, and Twitch live status
• DPS Calculator - Full combat simulator with prayers, potions, special attacks, bolt effects, raid scaling, and hit distribution
• Banked XP Calculator - 12 skills with 500+ items, equipment modifiers, and activity selection
• Group events - Scheduled events with 7 types, 50+ icons, event banners, and Discord webhook reminders
• Discord integration - Event notifications with rich embeds, item request messages with @mentions
• Skill XP graphing - Chart.js historical graphs with day/week/month/year periods and server-side aggregation
• OSRS blog page - Categorized Jagex RSS feed with YouTube and Twitch integration
• Real-time updates - Server-Sent Events with batched update processing and deduplication
• OSRS cache pipeline - Automated extraction via update-cache.ps1 for item data, sprites, map tiles, and equipment stats
• Hardened deployment - Docker Compose with health checks, resource limits, rate limiting, and structured logging

---

Self-Hosting

You can self-host the tracker instead of using groupiron.men. In the RuneLite plugin settings, set the URL to your hosted instance. Leaving it blank defaults to https://groupiron.men.

Prerequisites

• Docker
• Docker Compose

Quick Start (Docker Compose)

1. Copy docker-compose.yml and .env.example to your server.

2. Create a .env file from the example and fill in your secrets:

   cp .env.example .env

   See the comments in .env.example for an explanation of each variable.

3. Start the stack:

   docker compose up -d

The app will be available on port 4000 (configurable in the compose file). The PostgreSQL database is managed automatically.

Without Docker Compose

If you prefer to manage containers individually, set up a PostgreSQL database manually, then run the image with the required environment variables:

docker run -d -p 4000:4000 \
  -e PG_USER=<user> \
  -e PG_PASSWORD=<password> \
  -e PG_HOST=<host> \
  -e PG_PORT=<port> \
  -e PG_DB=<database> \
  -e BACKEND_SECRET=<secret> \
  joshuaalawrence/osrs-group-ironman-tracker:latest

---

Development

npm install    # Install dependencies
npm run dev    # Start local dev server with hot reload
npm run build  # Build server + site for production
npm test       # Run tests (via vitest)

Cache Updates

The OSRS cache pipeline downloads the game cache, extracts item data, sprites, map tiles, and equipment stats, then syncs everything to the frontend:

make update-cache         # Full cache update
make update-cache-push    # Full cache update with git commit & push
make update-equipment     # Re-import equipment.json from existing cache dump

See scripts/update-cache.ps1 for detailed options and flags.

---

Acknowledgments

• christoabrown/group-ironmen — Original group ironman tracker this project is forked from
• weirdgloop/osrs-dps-calc — Referenced for the DPS calculator implementation
• TheStonedTurtle/banked-experience — Referenced for the banked XP calculator

License

BSD 2-Clause - see LICENSE. Original work copyright (c) 2022, Christopher Brown.