BingOfTheRing

A multiplayer bingo webapp where players compete to complete custom phrase grids. Each player receives a unique randomly-ordered grid, and the first to complete it wins. Results are tracked on a leaderboard.

Features

• Multiplayer Bingo: Multiple players can play the same game with different randomized grids
• Custom Phrases: Create games with any phrases you want
• Real-time Leaderboard: Track who completed the game and when
• Admin Interface: Create and manage bingo games
• Persistent Storage: All data stored in JSON files, no database required
• Dockerized: Easy deployment with Docker and Docker Compose

Requirements

• Docker and Docker Compose (for containerized deployment)
• OR Node.js 20+ (for local development)

Quick Start

Using Docker (Recommended)

1. Clone the repository:

git clone <repository-url>
cd BingOfTheRing

2. Create environment file:

cp .env.example .env
# Edit .env and set your admin credentials

3. Build and run:

make build
make up

4. Access the application:

• Main app: http://localhost:3000
• Admin interface: http://localhost:3000/admin

Local Development

1. Install dependencies:

make install
# OR
npm install

2. Create .env file with required variables (see .env.example)

3. Run development server:

make dev
# OR
npm run dev

Usage

Creating a Game (Admin)

1. Navigate to http://localhost:3000/admin
2. Login with your admin credentials
3. Click "Create New Game"
4. Enter a game ID and phrases (one per line)
5. Set grid dimension (e.g., 5 for 5x5 grid)
6. Submit the form

Playing a Game

1. Navigate to http://localhost:3000/{gameId}
2. You'll be automatically assigned a unique grid
3. Click tiles to mark them as completed
4. When you complete the grid, enter your username
5. View the leaderboard at http://localhost:3000/{gameId}/leaderboard

Makefile Commands

• make build - Build Docker image
• make up - Start container (detached)
• make down - Stop container
• make logs - View container logs
• make shell - Open shell in container
• make dev - Run in development mode with hot reload
• make test - Run tests
• make install - Install dependencies locally
• make clean - Remove data directory (with confirmation)

Project Structure

BingOfTheRing/
├── src/
│   ├── server.js              # Express server entry point
│   ├── routes/                # Route handlers
│   ├── middleware/            # Custom middleware
│   ├── services/              # Business logic
│   ├── utils/                 # Utility functions
│   └── public/                # Frontend files
├── data/                      # Persistent data storage
│   ├── games/                 # Game definitions
│   └── grids/                 # Player grids
├── tests/                     # Vitest test files
├── Dockerfile                 # Container definition
├── docker-compose.yml         # Docker compose configuration
└── Makefile                   # Development commands

Environment Variables

See .env.example for all required environment variables:

• ADMIN_USERNAME - Admin login username
• ADMIN_PASSWORD - Admin login password
• SESSION_SECRET - Secret for session encryption
• PORT - Server port (default: 3000)

Data Storage

All data is stored in JSON files in the data/ directory:

• data/games/{gameId}.json - Game definitions
• data/grids/{gameId}/{gridId}.json - Player grids
• data/admin.json - Admin credentials (created automatically)

The data/ directory is mounted as a Docker volume for persistence.

Testing

Run tests with:

make test
# OR
npm test

License

MIT