OSRS Guild Map
Set up ha-osrs-map, a live map and tracker for your guild that reads from the hub.
OSRS Guild Map (ha-osrs-map) is a self-hosted website
that shows where every online guild member is, what they carry and wear, their skills and XP history,
and what the guild has been up to. It is a fork of
group-ironmen, reworked for guilds.
It reads every player from the hub. Players don't pair anything with the map; they only pair RuneLite with the hub, as usual.
RuneLite plugin ──pair/events──▶ osrs-data-hub ◀──GET /api/v1/snapshot (every 5 s)── map backend ──▶ site
▲ │
└──── /xp, /events, /locations, /leaderboards ◀─────┘ (cached)- The live map shows every online player in their own colour, with pings for loot, level-ups and deaths.
- Player profiles show vitals, gear, inventory, skills, XP gains, sessions and carried value.
- Trails follow up to eight players at once.
- The Clan page lists who's online and where, the top XP gainers, the biggest drops and the event feed.
- The admin portal manages users, roles and players, and tests the hub connection.
What you need
- A running hub, and an admin on it who can create an integration key.
- A machine with Docker and the Compose plugin. The map runs three containers: frontend, backend and PostgreSQL.
Set it up
Create an integration key on the hub
On the hub, open Admin → Integrations → Create integration key. Name it "Guild map" and give it these categories:
| Categories | Used for |
|---|---|
activity, location_live | the map and the player list |
stats, equipment, inventory | profiles and graphs |
events, location_history | the Clan page, map pings and trails |
Copy the key; it is shown once.
A personal key works too
A personal key from API keys also works, with lower limits: 120 requests a minute instead of 600,
10 accounts per request instead of 50, no account_hash matching, and it stops working when its creator
leaves the guild. The map logs a warning when it runs on one.
Get the compose files
git clone https://github.com/RedFirebreak/ha-osrs-map.git
cd ha-osrs-map
cp .env.example .envPoint it at your hub
In .env, set the hub URL (without /api/v1) and the key. The backend refuses to start without them.
HUB_BASE_URL=https://hub.example.com
HUB_API_KEY=ohub_xxxxxxxxxx_xxxxxxxxAlso set a database password (PG_PASSWORD), and, if the site will be public before you create the
admin account, a SETUP_TOKEN (openssl rand -hex 32).
Start it
docker compose up -dThe site listens on http://localhost:4000. Put it behind your reverse proxy with HTTPS. Only the
frontend needs to be reachable.
Plain HTTP
On plain http://localhost also set COOKIE_SECURE=false, or the browser drops the login cookie.
Create the admin and test the connection
The first visit asks you to create the admin account. Then open Admin → All Players → Test connection. It checks the key and shows how many accounts it can read.
Players choose what the map shows
The map shows exactly what the hub shares with the guild. On the hub, live location is shared with the guild by default, but equipment, inventory and the location trail are private until the owner shares them. A player whose items don't show up on the map should change their sharing settings on the hub. A profile tab or trail says "not shared" until they do.
Optional settings
| Variable | Default | Purpose |
|---|---|---|
HUB_POLL_INTERVAL_SECS | 5 | How often the backend polls /snapshot (at least 2). |
HUB_HISTORY_ENABLED | true | Serve graphs, trails and the events feed from the hub. |
HUB_REQUEST_BUDGET | 80 % of the key's limit | Hub requests per minute the map allows itself. |
DISCORD_CLIENT_ID, DISCORD_CLIENT_SECRET, DISCORD_REDIRECT_URI | "Log in with Discord". The redirect URI is https://<site>/login/discord. | |
DISCORD_AUTO_REGISTRATION, DISCORD_AUTOREG_SERVERS | false | Let members of your Discord server create a map account by logging in. |
SITE_TITLE, SITE_NAME | OSRS Guild Map | Branding. |
The map's README has the full list, a Kubernetes deployment contract, and a mock hub for trying the map without a real hub.
How it uses the hub
- The backend polls
/snapshotwithETagandsince, and does a full refresh every two minutes. The key never leaves the server. - Presence comes from the hub's
onlineandlast_seen. If the sync stops for five minutes, everyone shows as offline. - Graphs, trails, gains, profiles and the events feed are served from a short-lived cache, so the hub sees the same number of requests however many people view the map.
- Accounts are matched by hub account id, then by
account_hash(service keys only), then by name. When the hub reports an owner's Discord id, the player is linked to the map user who logged in with that Discord account.