Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Antonelli-Tech-Solutions/spades/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through cloning the Spades Online repository, configuring your environment, running the database migrations, and starting the server locally. By the end you will have a fully functional game server running on your machine with the built-in web client accessible in your browser — no build step required.

​
Prerequisites

Before you begin, make sure you have the following installed and running on your machine:
  • Node.js 18+ — the server uses ES Modules and native node:crypto
  • PostgreSQL — any recent version; used for player accounts, game history, and social data
  • Redis — any recent version; used for sessions, lobby state, presence, and pub/sub

​
Setup

1

Clone and install

Clone the repository and install dependencies. There is no build step — the server runs directly from source using Node.js ES Modules.
git clone https://github.com/Antonelli-Tech-Solutions/spades.git
cd spades
npm install
2

Start PostgreSQL and Redis

Make sure both services are running before you proceed. If you installed them via a package manager or Docker, start them with your usual commands. Your connection strings will look something like these:
PostgreSQL: postgresql://user:password@localhost:5432/spades
Redis:      redis://localhost:6379
Create the spades database in PostgreSQL if it does not already exist:
createdb spades
3

Set environment variables

The server reads all configuration from environment variables. Only two are required to start:
export DATABASE_URL="postgresql://user:password@localhost:5432/spades"
export REDIS_URL="redis://localhost:6379"
Replace user and password with your PostgreSQL credentials. See the Environment Variables reference for the full list of optional settings.
4

Run database migrations

Apply all five migrations in order. Each file is idempotent (CREATE TABLE IF NOT EXISTS) so it is safe to re-run them.
psql $DATABASE_URL -f db/migrations/001_create_players.sql
psql $DATABASE_URL -f db/migrations/002_create_profile_and_games.sql
psql $DATABASE_URL -f db/migrations/003_create_password_reset_tokens.sql
psql $DATABASE_URL -f db/migrations/004_create_friendships.sql
psql $DATABASE_URL -f db/migrations/005_create_player_blocks.sql
5

Start the server

Start the server with:
npm start
The server listens on port 3000 by default. Open http://localhost:3000 in your browser to access the web client. You should see the Spades Online sign-in screen.
Spades Online server listening on port 3000
WebSocket server sharing HTTP server on port 3000

​
Development Shortcuts

​
Skip email verification

If you do not have an SMTP server configured, verifying accounts via email is not possible. Set DEV_AUTO_VERIFY=true when starting the server to mark new registrations as verified immediately — no email is sent and you can log in straight away: 
DEV_AUTO_VERIFY=true npm start
DEV_AUTO_VERIFY=true bypasses all email verification. Never set this variable in a production environment. It is a local development convenience only.

​
Bot players

You can fill any empty seat at a table with a bot player to test gameplay without needing four human players. The table host sends a request specifying the target seat: 
POST /api/tables/:tableId/add-bot
x-session-id: <sessionId>
x-player-id: <playerId>
Content-Type: application/json

{ "seat": "north" }
Bot players bid by counting the spades in their hand and play a random legal card. Their turns are processed automatically server-side — human players just poll GET /api/tables/:tableId/state as normal. Once all four seats are filled (by any mix of humans and bots), the game starts automatically.

​
Running Tests

npm test
Unit tests cover the game engine, anti-cheat validation, lobby logic, and middleware, and run without any external services. Integration tests require DATABASE_URL to be set and will be skipped if it is absent. To run the linter separately: 
npm run lint
This runs ESLint against the test/integration directory. The same check runs in CI before the test suite.

​
Next Steps

Environment Variables

Configure SMTP email, custom ports, rate limiting, and more.

Architecture

Understand how the WebSocket engine, Redis pub/sub, and game state machine work together.

Build docs developers (and LLMs) love

Get started for freeTalk to us