Self-Hosting a Multiplayer Mahjong Table

mahjong-docker is a full-stack online Mahjong game packaged for self-hosting. It supports custom rooms, human players, heuristic computer opponents, session recovery after a refresh or disconnect, and a responsive interface designed for both desktop and touch screens.

The React and TypeScript frontend renders a high-resolution vector tile set, themes, hands, discards, prompts, and room state. The Node.js, Express, and Socket.IO backend owns the game state machine, scoring, room lifecycle, and reconnect behavior. The rules engine supports drawing, discarding, chi, pong, kong, flower replacement, self-draw wins, and wins from another player's discard, with claim priority handled by the server.

Start a local build

With Docker and Docker Compose installed:

git clone https://github.com/Alchemist-Aloha/mahjong-docker.git
cd mahjong-docker
docker compose up --build

Open http://localhost:53000. The repository also publishes frontend and backend images on GHCR for deployments that should not compile locally. In production, place the frontend behind a TLS-terminating reverse proxy and preserve WebSocket forwarding for Socket.IO.

The bots use hand-value heuristics rather than a general game-playing model. They preserve useful pairs and sequence shapes, discard isolated tiles, and vary some calls to avoid perfectly mechanical play. That keeps local games moving without pretending the computer players are tournament-level opponents.

Visit the Mahjong Docker repository for deployment examples and the detailed architecture documents under docs/.