Hearts

A multiplayer Hearts card game with real-time gameplay via WebSockets. Shares accounts with Hokm — log in with the same credentials on both games.

Requirements

• Docker & Docker Compose
• Hokm installed at /root/hokm (provides card assets and shared user accounts)

Install

git clone https://git.goyban.com/goyban/hearts.git
cd hearts
cp .env.example .env
# edit .env — see below

Then start:

docker compose up -d --build

Or use the helper script (stops, rebuilds, and tails logs):

./rerun.sh

The game is available at:

• HTTP: http://<host>:4000
• HTTPS: https://<host>:4443 (self-signed cert, needed for PWA install)

.env reference

# Secret used to sign JWT session tokens. Change this to a random string.
JWT_SECRET=hearts-secret-change-me

# Username that gets admin privileges (access to /admin panel).
# Leave empty to disable admin.
ADMIN_USERNAME=

# HTTP and HTTPS ports (must match docker-compose.yml port mapping if changed).
PORT=4000
HTTPS_PORT=4443

# Path to Hokm's users.json so Hokm accounts work here too.
# Docker path (default, matches the volume mount in docker-compose.yml):
SHARED_USERS_FILE=/hokm-data/users.json
# If running directly with `node server.js` instead of Docker, use:
# SHARED_USERS_FILE=/root/hokm/data/users.json

# Optional: Resend (resend.com) for email verification codes on signup.
# Leave blank to skip email verification entirely.
RESEND_API_KEY=
RESEND_FROM=noreply@example.com

# Optional: Cloudflare Turnstile CAPTCHA on the signup form.
# Get keys at dash.cloudflare.com → Turnstile.
# Leave blank to disable CAPTCHA.
TURNSTILE_SITE_KEY=
TURNSTILE_SECRET=

Minimum required changes

Variable	What to set
JWT_SECRET	Any long random string (e.g. openssl rand -hex 32)
ADMIN_USERNAME	Your username, to unlock the admin panel

Everything else is optional.

Updating

git pull
./rerun.sh

Data

Game data (users, stats, config) is stored in ./data/ which is bind-mounted into the container. It persists across restarts and rebuilds.