Microchess
Self-contained PHP 8.2+ application. Set the document root to this web/ directory. No Composer, Node, build step or files outside this directory are required in production.
Run locally
From the repository root:
php -S 127.0.0.1:8080 -t web web/router.php
Open http://127.0.0.1:8080. You are automatically signed in as test_user_1. Account → Switch to test_user_2 switches accounts. Use a second browser profile or private window for two independent sessions. Test accounts are created on first use, with no fabricated friends or games.
Autologin works with PHP's development server, Apache and PHP-FPM. It requires both a loopback client IP and a localhost/loopback Host header; public domains do not enable test accounts. A previous OAuth session on localhost is replaced with test_user_1; a selected test account remains selected. Do not expose the local development site through a public proxy.
Production
Requirements: PHP 8.2+, PDO SQLite, cURL, writable web/data/, and HTTPS. All application writes (database, SQLite WAL/SHM, sessions and application error log) remain under web/data/. Session contents, games, move histories, invitations, friendships and results are stored in SQLite. The app does not write to a system temporary or session directory.
On the first page request, the app creates web/data/config.php with empty base_url, client_id and client_secret fields if the file does not exist. Existing files are never overwritten. This file is ignored by Git and excluded from deployment with the rest of data/. Fill it in on each server, for example:
<?php
return [
'base_url' => 'https://your-chess-domain.example',
'client_id' => 'your-registered-domain.example',
'client_secret' => 'your-client-secret',
];
Environment equivalents: MICROCHESS_BASE_URL, MICROCHESS_CLIENT_ID, MICROCHESS_CLIENT_SECRET. Empty or missing config fields fall back to these environment variables; populated fields in the file take precedence. The base URL may include a subdirectory and must not have a trailing slash.
Register your client domain and /callback.php (or /subdirectory/callback.php) in the auth service admin. Integration follows the service's integration guide: state validation, server-side code exchange, /api/me validation, session renewal and logout. Credentials and bearer tokens never enter client JavaScript. Provider validation occurs at most once per minute during active use; sessions expire after an hour of inactivity. OAuth itself requires the real registered client credentials to test.
Apache: enable AllowOverride All for this directory so the included .htaccess files deny access to data/, lib/ and tests/, and disable directory listings. Nginx does not read .htaccess; add equivalent deny rules before your PHP location and adjust the prefix if mounted in a subdirectory:
location ~* ^/(data|lib|tests)(/|$) { deny all; }
location ~ /\. { deny all; }
location ~* ^/(README\.md|router\.php)$ { deny all; }
Use a normal PHP-FPM configuration that only executes existing PHP files. Verify that /data/microchess.sqlite, /data/config.php and /lib/bootstrap.php return 403 before putting real data in the app. Only the PHP user should have filesystem write access to data/.
Deploy this directory's contents. Preserve the entire production data/ directory: exclude data/ itself and all descendants from upload and deletion, including config.php, .htaccess, the database and WAL files. The included CI script creates data/ and installs its .htaccess separately before mirroring; do the same when deploying manually. Never upload your development database or tests/artifacts/. The root .gitlab-ci.yml runs PHP syntax, chess/API tests, JavaScript syntax checks and an isolated FTP deployment test before deploying master. Deployments are serialized with a production resource group. FTP credentials are passed to lftp through its password environment variable; FTP TLS certificate verification is disabled for this hosting account, as configured by the owner.
SQLite supports a single application instance with concurrent requests; writes use BEGIN IMMEDIATE, game versions reject stale actions, and invitation acceptance is atomic. Keep the database on local persistent storage. Use SQLite's backup API for live backups; copying just the .sqlite file while WAL is active can miss transactions.
Game behavior
Initial position, viewed from White:
5 k n b r
4 p . . .
3 . . . .
2 . . . P
1 R B N K
a b c d
White moves first. Pawns move one square, never double-step; there is no castling or en passant. Promotion is mandatory to queen, rook, bishop or knight. The server generates legal moves and checks king safety. Checkmate and stalemate are evaluated after every move. Standard insufficient material positions (bare kings, lone bishop/knight, only bishops on one square color) draw automatically. Threefold repetition and the 50-move rule can be claimed from the game menu, including using an intended legal move; fivefold repetition and 75 moves are automatic, with checkmate taking precedence. A draw can also be offered or the game resigned from your turn's menu.
The top grid includes your moves, incoming challenges and finished games. Opponent-turn games and sent challenges are noninteractive in the lower grid. Boards orient toward your color. Polling updates the other player every 2.5 seconds while the tab is visible. No clocks or timeouts are applied to games.
A friend invitation is valid for one month and can be accepted once. Accepting inserts one symmetric friendship; either player can remove it. Direct challenges require friendship. Match links likewise expire after one calendar month and are consumed only by acceptance; dismissing/rejecting the modal preserves the link. An expired link cannot be accepted. Both link types survive the login redirect.
Rematches need both players' agreement and swap colors, keeping the tile ID. Exit hides a completed tile only for that player and disables rematch for both. Historical results remain available for friend statistics, even after removal/re-adding. Account → Export my data (JSON) exports the user's profile, relationships, invitations, games and historical results.
Avatars
Click your avatar at the bottom of the friends sidebar to open the piece picker. The local collection contains 29 colored standard and fairy chess avatars, with color/family filters and an option to choose randomly. Accounts without an avatar receive a random piece automatically. Selection is saved in SQLite and appears in friend lists, opponent tile headers and your data export. The user_avatars table is created automatically, preserving existing accounts and game data.
Avatars use locally stored PNG previews from Wikimedia Commons; available original SVGs are included alongside them. Author, original file and license links are recorded in avatar credits and assets/avatars/catalog.json. There are no runtime requests to Wikimedia.
Checks
From the repository root:
find web -name '*.php' -not -path '*/artifacts/*' -print0 | xargs -0 -n1 php -l
php web/tests/chess.php
python3 web/tests/integration.py
node --check web/assets/app.js
Engine tests cover movement, pins, king safety, promotions, endings, draw thresholds and deterministic random games. API tests start an isolated copy under web/tests/artifacts/, covering two sessions, CSRF, invitations, bilateral friendship, turn enforcement, stale actions, rematches, statistics, export and protected paths. They run four PHP workers, verify concurrent link acceptance, remove the isolated copy afterwards and never touch the real database.
Optional real-browser tests (requires Node.js):
npm install --prefix web/tests/artifacts --no-audit --no-fund playwright
PLAYWRIGHT_BROWSERS_PATH="$PWD/web/tests/artifacts/browsers" web/tests/artifacts/node_modules/.bin/playwright install chromium
PLAYWRIGHT_BROWSERS_PATH="$PWD/web/tests/artifacts/browsers" node web/tests/browser.mjs
These cover click, mouse drag, touch drag, promotion, rematch, friendships, desktop and mobile layouts. Screenshots are written under web/tests/artifacts/; the application copy and its database are discarded.
Piece credits
Unmodified Chess_{piece}{l|d}t45.svg images by Cburnett, downloaded from Wikimedia Commons, used under Creative Commons Attribution-ShareAlike 3.0. See asset credits for individual source links. The rules dialog includes visible attribution. The Microchess starting position follows Green Chess.
Inactive games and final positions
Ended games retain the final board and move highlights, with a transparent result bar that becomes readable on hover or keyboard focus. Touch devices show readable controls immediately. After seven days without game activity, either player can confirm removal of both tiles. Existing result history is retained; stopping an unfinished game awards no result. Activity tracking begins at deployment for existing games because earlier move timestamps were not stored.