Bingo App

A lightweight Python app that renders a 5×5 bingo board with configurable text. Tailor the quotes to match your own theme and rediscover the fun of bingo in browser form. Inspired by ipv6bingo.com.

Screenshot

Quickstart

Option A: run with Docker

docker run -p 8080:8080 ghcr.io/lundgrenolof/bingo-app:latest

Option B: run locally

git clone https://github.com/lundgrenolof/bingo-app.git
cd bingo-app
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
python3 app.py

Then point your browser to http://localhost:8080.

Configuration precedence is environment variables → config/config.ini → built-in defaults.

Customize the board by editing config/quotes.txt (one quote per line).

Environment variables

• APP_TITLE – custom heading shown on the page (defaults to Codex Todo Bingo)
• APP_TAGLINE – optional subtitle shown beneath the heading (defaults to Mark every standup buzzword before the sprint ends.)
• BUTTON_LOCATION – choose where Shuffle/Clear buttons render (top/bottom, defaults to bottom)
• BUTTON_COLOR – override the accent colour (hex like #1d73ff, defaults to #1d73ff)
• PORT – override the listening port (1–65535, defaults to 8080)
• QUOTES_FILE – path to the quotes file (defaults to config/quotes.txt)
• CONFIG_FILE – alternate config path (defaults to config/config.ini)

Supply a quotes file (one entry per line, # prefixes treated as comments). See the bundled quotes.txt for inspiration.

Config file

Edit config/config.ini to tweak UI defaults without touching environment variables:

[app]
app_title = My Custom Title
app_tagline = Optional subtitle
button_location = bottom
button_color = #1d73ff

[server]
port = 8080

Point the app at an alternate config via CONFIG_FILE=/path/to/config.ini. Docker users can mount their override with -v $(pwd)/config:/bingoapp/config:ro.

Precedence for each option is: environment variable → config/config.ini → built-in defaults. Invalid ports fall back to 8080.

Bingo Board UX

• 5×5 responsive grid of quotes
• Shuffle button picks a fresh 25 quotes each round in the browser
• Clear button wipes selections; full page refreshes start with a clean board
• Accessible buttons, keyboard toggling, and inline status updates
• Strict CSP with no external assets: inline CSS/JS only, plus unsafe-inline allowed for style blocks
• Honors light and dark mode preferences

Operational Notes

• Mount sanitized quote files at config/quotes.txt; the app falls back to an empty board if the file is missing.
• Blank lines and comment lines (# ...) are ignored. Quotes are deduplicated while preserving the first occurrence.
• Configuration and quote files are cached in memory and reloaded only when the file’s modified time changes.
• Health endpoint (/healthz) returns { "status": "ok" } for simple liveness checks.

Docker

The image runs on both linux/amd64 and linux/arm64.

The image ships with default config/config.ini and config/quotes.txt. Mount your own files (or an entire config/ directory) to /bingoapp/config to override them.

All configuration files live under /bingoapp/config, and the container entrypoint runs from /bingoapp.

Docker run

docker run -p 8080:8080 ghcr.io/lundgrenolof/bingo-app:latest

Docker Compose

services:
  bingo:
    image: ghcr.io/lundgrenolof/bingo-app:latest
    container_name: bingo-app
    ports:
      - "8080:8080"
    environment:
      APP_TITLE: "Bingo App"
      QUOTES_FILE: "/data/quotes.txt"
      PORT: "8080"
    volumes:
      - ./quotes.txt:/data/quotes.txt:ro
    restart: unless-stopped

Start the stack with docker compose up -d, adjusting the bind mount or environment variables as needed for your environment.

Build Locally

git clone https://github.com/lundgrenolof/bingo-app.git
cd bingo-app
docker build -t ghcr.io/lundgrenolof/bingo-app:latest .
docker run \
  -p 8080:8080 \
  -v $(pwd)/config:/bingoapp/config:ro \
  ghcr.io/lundgrenolof/bingo-app:latest

Tests

Activate your virtualenv, install dependencies (including pytest), then run the suite:

. .venv/bin/activate
pip install -r requirements.txt
pip install pytest
python3 -m pytest

The tests touch the Bottle WSGI app directly, checking quote parsing and security headers.

License

MIT License. See LICENSE for details.