Skip to content
All projects

wardogs.id

A live directory of WARDOGS community servers with occupancy history, player stats and a moderated submission queue.

Role
Sole author
Period
2026-09 → now
Status
active
Stack
TypeScript, React, Fastify, PostgreSQL, Docker, Caddy, Playwright
Uncached directory snapshotproduction VPS, 1,516 real listings, 2026-09-2937.43 ms median
Directory over public HTTPSbounded 340-request check, 0 errors111.92 ms p95
Handler at concurrency 100measured inside the API, without the network34.32 ms p95

Overview#

wardogs.id is a directory of community servers for the game WARDOGS. It imports the public server list, records how busy each server is over time, and builds player leaderboards from approved public match data. Anyone can submit a server, and submissions wait in a queue until I approve them. The site is live at wardogs.id.

The frontend is React and Vite, the API is Fastify, and the data lives in PostgreSQL. Caddy handles HTTPS. Everything runs in Docker on one OVH VPS, and I built and run all of it.

Problem#

The existing server lists show who is online right now. They don't show whether a server is usually busy at the times you play, and they miss community servers that aren't on the official list.

Accepting submissions from anyone creates a second problem. The site has to take input from strangers without letting any of it reach the public directory unchecked.

The problem I didn't see coming was data. I didn't know how much I'd end up collecting on a £6 a month VPS. Every server gets observed every few minutes, and every finished match adds player rows, so a lot of the work turned into keeping that small enough to stay fast on cheap hardware.

Constraints#

  • One VPS with 4 vCPUs and 8 GB of RAM. If it goes down, the site goes down.
  • The upstream source updates about every 180 seconds, and I shouldn't poll it faster than that.
  • Submissions are anonymous, and approving one doesn't prove the submitter owns the server.
  • The target was over 10,000 visitors a day without putting a CDN cache in front.

Architecture#

Caddy terminates TLS and serves the built frontend. The API and the database sit on private Docker networks and expose no ports to the internet. Separate collector processes poll the public data sources and write through their own database roles. The API reads from views that only include public fields.

The browser downloads the directory once, then revalidates it with an ETag. It renders 50 rows per page. Tabs in the background stop polling, and visible tabs refresh about once a minute with a little random jitter.

Technical decisions#

Database roles decide what each process can do#

The API connects with a role that can read the public views and call two functions, one for submissions and one for reports. It can't read the private tables, publish a listing or delete anything. Each collector has its own role that can only call its own ingestion function. If someone took over the API process, they would only get those same permissions.

A short cache that checks for changes#

The API caches the serialised directory for five seconds, and requests that arrive during a rebuild wait for the same database read. Every request still checks a small revision number, so approving or hiding a listing takes effect straight away. If that check fails, the API returns an error. I'd rather show an error than risk serving a listing that was just hidden.

Keep only the data that earns its space#

Occupancy history is deleted after 30 days, with an index on the timestamp so the cleanup stays cheap. Servers that stop appearing in the public list drop out after 7 days. When a match is imported, only the player totals that match touches are rebuilt from their facts, not the whole leaderboard. A match that ended more than two days ago is rechecked weekly instead of every ten minutes. Player facts don't expire yet, which the repo flags as the next thing to watch before more servers are added.

Old readings stay visible with their age#

When a server's latest count is past the live cutoff, the site keeps showing the last count along with how old it is. It doesn't turn it into a zero. Servers that have never been measured show a dash.

Trade-offs#

The first page load downloads the whole directory, about 1 MB before compression with roughly 1,500 listings. That's simpler than paginating on the server, and it's fine at this size. It will need replacing before the directory gets near its documented limits of 22,000 servers and 2,000 players.

Running on one VPS keeps the cost and the moving parts down. Daily local backups are set up and restoring them has been tested. Off-site backups and failure alerts aren't done yet, and the security review in the repo lists both.

Implementation details#

Every privileged action goes through a database function with explicit grants. Here the collector's ingestion function is restricted to the collector's role.

db/migrations/003_activity.sql (excerpt)
REVOKE ALL ON FUNCTION wardogs_public.ingest_snapshot(jsonb) FROM PUBLIC;
GRANT EXECUTE ON FUNCTION wardogs_public.ingest_snapshot(jsonb) TO wardogs_worker;

Submission limits are enforced inside Postgres as well as in the API. Each client gets three submissions an hour and ten a day, with 100 a day across the whole site. The database stores HMAC hashes of client addresses instead of raw IPs. Searches are plain substring matches passed as parameters, and users can't control the sort expression.

The API tests cover schema and origin checks, search and rate limits. Browser tests cover how user text is rendered, tampered local storage, the content security policy and layouts at different sizes. A separate script runs against the full stack and checks the real database role permissions through Caddy.

Outcomes#

I measured the production VPS on 29 September 2026, with 1,516 real listings. Building the directory snapshot without a cache took a median of 37.43 ms. Inside the API, 1,500 conditional requests needed only one snapshot build, and with 100 running at once the 95th percentile was 34.32 ms. Over public HTTPS, a 30-second test of 340 requests had no errors, and the directory endpoint's 95th percentile was 111.92 ms. HTTP 304 answered 26 of the 30 directory requests.

That's enough for the 10,000 visitors a day target with this workload. It doesn't show the site could handle 10,000 people at the same moment, and the HTTPS test ran from a single machine close to the server.