♚♛♜♝♞

Chess

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

# View all build options
make help

# 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