Go backend server providing a RESTful API for chess gameplay with user authentication. Integrates Stockfish engine for move validation and computer opponents.

Features

RESTful API for chess operations
User registration and JWT authentication
Stockfish engine integration for validation
Human vs human, human vs computer, computer vs computer modes
Custom FEN position support
Asynchronous engine move calculation
Configurable engine strength and thinking time
SQLite persistence with async writes for games
User management with secure Argon2 password storage
PID file management for singleton enforcement
Database CLI for storage and user administration

Requirements

Go 1.25+
Stockfish chess engine (stockfish in PATH)
SQLite3 (for persistence features)

Installation

# Arch Linux
yay -S stockfish

# FreeBSD
pkg install stockfish

Quick Start

Using Make (Recommended)

git clone https://github.com/lixenwraith/chess
cd chess
make build

# Standard mode with persistence and auth
make run-server

# Or run with web UI
make run-server-web

# Initialize database with user support
make db-init

# Add users via CLI
./bin/chess-server db user add -path db/chess.db -username alice -password AlicePass123

Building Manually

#git clone https://git.lixen.com/lixen/chess # Mirror
git clone https://github.com/lixenwraith/chess
cd chess
go build ./cmd/chess-server

# Standard mode with persistence and auth
./chess-server -storage-path chess.db

# Development mode with all features
./chess-server -dev -storage-path chess.db -pid /tmp/chess-server.pid -pid-lock -port 9090

# Initialize database with user support
./chess-server db init -path chess.db

# Add users via CLI
./chess-server db user add -path chess.db -username alice -password AlicePass123
./chess-server db user list -path chess.db

Server listens on http://localhost:8080. See API Reference for endpoints including authentication.

User Management

The chess server supports user accounts with secure authentication:

Creating Users

# Add user with password
./chess-server db user add -path chess.db -username alice -email alice@example.com -password SecurePass123

# Interactive password prompt
./chess-server db user add -path chess.db -username bob -interactive

# Import with existing hash
./chess-server db user add -path chess.db -username charlie -hash '$argon2id$...'

Managing Users

# List all users
./chess-server db user list -path chess.db

# Update password
./chess-server db user set-password -path chess.db -username alice -password NewPass456

# Update email
./chess-server db user set-email -path chess.db -username alice -email newemail@example.com

# Delete user
./chess-server db user delete -path chess.db -username alice

Web UI

The chess server includes an embedded web UI for playing games through a browser.

Enabling Web UI

# Start with web UI on default port 9090
./chess-server -serve

# Custom web UI port  
./chess-server -serve -web-port 3000 -web-host 0.0.0.0

# Full example with authentication enabled
./chess-server -dev -serve -web-port 9090 -api-port 8080 -storage-path chess.db

Features

Visual chess board with drag-and-drop moves
Human vs Computer gameplay
Configurable engine strength (0-20)
Move history with algebraic notation
FEN display and custom starting positions
Real-time server health monitoring
User authentication support
Responsive design for mobile devices

Access the UI at http://localhost:9090 when server is running with -serve flag.

Documentation

API Reference - Endpoint specifications including auth
Architecture - System design with auth layer
Development - Build, test, and user management
Client Guide - Interactive debugging client
Stockfish Integration - Engine communication

License

BSD 3-Clause

Languages

Go 56.3%

Shell 19.4%

JavaScript 15.1%

CSS 5.6%

Makefile 2%

Other 1.6%