Self-hosting overview

Run your own Wordgrid instance with a custom leaderboard backend powered by Flask and MongoDB.

Self-hosting Wordgrid gives you full control over the leaderboard server and lets you serve the game from your own domain. You can customize the backend, point the frontend at your own API, and keep all player data in your own MongoDB instance.

What you get

• Your own leaderboard server — a Python Flask API backed by MongoDB, handling score submission and retrieval for daily boards.
• Custom domain hosting — serve the static frontend files from any host you choose, and point them at your own API.

Architecture

Wordgrid is split into two independent parts:

Frontend — a set of static files that run entirely in the browser. No build step required.

File	Purpose
index.html	Game markup and UI
app.js	Game logic and API client
style.css	Styles
words.txt.gz	Compressed word list

Backend — a Python Flask server that stores and retrieves leaderboard scores in MongoDB.

Browser (app.js)
      │
      │  GET /leaderboard/:date
      │  POST /leaderboard
      ▼
Flask API (main.py)
      │
      ▼
MongoDB — "leaderboard" collection

Requirements

• Python 3.x — to run the Flask server
• MongoDB — local instance or a cloud provider such as MongoDB Atlas
• Static file server — any server capable of serving static files: Nginx, Caddy, GitHub Pages, Netlify, and similar options all work

Setup steps

1. Set up the Flask server

   Install dependencies, configure environment variables, and start the server. See Server setup.

2. Configure the frontend

   Update API_URL in app.js to point at your server. See Configuration.

3. Serve the frontend

   Copy the static files to your chosen host and serve them over HTTP/HTTPS.

Next steps

Server setup

Install dependencies and run the Flask leaderboard server locally or in production.

Configuration

Configure environment variables and connect the frontend to your server.