ChessServer

ChessServer has hosted rooms with two player seats and observers. Mix humans, eight-level Lynx engines and language models in any pairing; hosts arrange players and start each game. Players can chat, and signed-in players and organizers can replay saved games and export PGN. Built on Aiursoft Template with optional server-controlled clocks.

Play with a guest nickname, or sign in with a local account or OIDC to save your games; see Configuration.

Try

Try a running ChessServer here.

Install with Docker

Run the installer with the desired port (omit it to choose an available port):

curl -fsSL https://raw.githubusercontent.com/aiursoftweb/chessserver/master/install.sh | sudo bash -s -- 8080

Installation starts after three seconds; press Ctrl+C to cancel. Then open http://localhost:8080.

Run manually

Requirements about how to run

1. Install .NET 10 SDK and Node.js.
2. Execute npm install at wwwroot folder to install the dependencies.
3. Execute dotnet run to run the app.
4. Use your browser to view http://localhost:5000.

Run in Microsoft Visual Studio

1. Open the .sln file in the project path.
2. Press F5 to run the app.

Run in Docker

First, install Docker here.

Then run the following commands in a Linux shell:

image=aiursoft/chessserver
appName=chessserver
sudo docker pull $image
sudo docker run -d --name $appName --restart unless-stopped -p 5000:5000 -v /var/www/$appName:/data $image

That will start a web server at http://localhost:5000 and you can test the app.

The docker image has the following context:

Properties	Value
Image	aiursoft/chessserver
Ports	5000
Binary path	/app
Data path	/data
Config path	/data/appsettings.json

How to contribute

There are many ways to contribute to the project: logging bugs, submitting pull requests, reporting issues, and creating suggestions.

Even if you with push rights on the repository, you should create a personal fork and create feature branches there when you need them. This keeps the main repository clean and your workflow cruft out of sight.

We're also interested in your feedback on the future of this project. You can submit a suggestion or feature request through the issue tracker. To make this process more effective, we're asking that these include more information to help define them more clearly.

Configuration

Local accounts and passwords are enabled by default. For production OIDC sign-in, set the environment variable AppSettings__AuthProvider=OIDC and configure AppSettings__OIDC__Authority, AppSettings__OIDC__ClientId, and AppSettings__OIDC__ClientSecret for your identity provider. Register https://<your-host>/signin-oidc as its callback. Guests can play without signing in.

SQLite stores accounts and chess sessions by default. Existing Docker installations retain /data/appsettings.json when upgrading; to switch an existing OIDC installation to local sign-in, set AppSettings__AuthProvider=Local or update AppSettings:AuthProvider in that file. Keep the database and data-protection keys to resume games after a restart.

For an LLM opponent, set OpenAI:CompletionApiUrl to the full Chat Completions URL, such as https://your-service-address/v1/chat/completions, and configure the server-side OpenAI:Token in appsettings.json (or use OpenAI__CompletionApiUrl and OpenAI__Token environment variables). A hostname or /v1 base URL alone is insufficient. The same service must support GET https://your-service-address/v1/models with that token; its model IDs populate the choices. OpenAI:Model is an optional preferred model, not a replacement for the models endpoint.

Restart the application after changing these settings, sign in, then create a room and select Add AI → LLM → model. The original eight engine levels remain available.