Skip to main content
The Wordgrid leaderboard server is a small Flask application that stores and serves scores for daily boards. It connects to MongoDB and exposes two endpoints: one to fetch scores for a given date, and one to submit a new score.

​
Prerequisites

  • Python 3.x and pip
  • A running MongoDB instance (local or cloud)

​
Setup

1

Get the server files

Clone the repository or download the server/ directory from the Wordgrid source.
git clone https://github.com/proplayer919/wordgrid.git
2

Navigate to the server directory

cd wordgrid/server
3

Install dependencies

pip install -r requirements.txt
This installs the following packages:
PackagePurpose
flaskHTTP server and routing
flask-corsCross-Origin Resource Sharing support
pymongoMongoDB client
python-dotenvLoads environment variables from .env
4

Create your .env file

Copy the example file and fill in your values:
cp .env.example .env
Then edit .env with your MongoDB connection string and preferred port. See Configuration for all available variables.
5

Start the server

python main.py
The server starts on 0.0.0.0 and listens on the port defined by the PORT environment variable (default: 5000).

​
Server behaviour

Host and port — the server always binds to 0.0.0.0, making it reachable on all network interfaces. The default port is 5000. 
app.run(host="0.0.0.0", port=port, debug=debug)
Debug mode — defaults to True. Flask debug mode enables the interactive debugger and auto-reloads on code changes. 
debug = os.getenv("DEBUG", "True") == "True"
CORS — enabled globally via flask_cors.CORS(app). All origins are permitted by default, which allows the frontend to call the API from any domain. MongoDB collection — scores are stored in a collection named leaderboard within the database specified in your MONGO_URI. The database name is taken from the URI path (e.g., mongodb://localhost:27017/wordgrid uses the wordgrid database). 
leaderboard_collection = db["leaderboard"]

​
API endpoints

MethodPathDescription
GET/leaderboard/<date>Returns all scores for the given date (format: YYYY-MM-DD), sorted ascending by score.
POST/leaderboardSubmits a new score. Expects JSON body with name (string), score (integer), and date (string).

​
Production deployment

Set DEBUG=False in your .env file before deploying to production. Running Flask’s development server in production is not recommended.
For production, use a WSGI server such as Gunicorn instead of python main.py: 
pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 main:app
The server runs on 0.0.0.0 by default. If you expose it directly to the internet, ensure your firewall and MongoDB instance are configured appropriately. Consider placing the server behind a reverse proxy such as Nginx or Caddy.

Build docs developers (and LLMs) love

Get started for freeTalk to us