# 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: ```sh 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 '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](https://auth.timfalken.com/admin). Integration follows the service's [integration guide](https://auth.timfalken.com/help): 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: ```nginx 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: ```text 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](assets/avatars/CREDITS.md) and `assets/avatars/catalog.json`. There are no runtime requests to Wikimedia. ## Checks From the repository root: ```sh find web -name '*.php' -not -path '*/artifacts/*' -print0 | xargs -0 -n1 php -l php web/tests/chess.php python3 web/tests/startup.py 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): ```sh 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](https://commons.wikimedia.org/wiki/Category:SVG_chess_pieces), used under [Creative Commons Attribution-ShareAlike 3.0](https://creativecommons.org/licenses/by-sa/3.0/). See [asset credits](assets/pieces/CREDITS.md) for individual source links. The rules dialog includes visible attribution. The Microchess starting position follows [Green Chess](https://greenchess.net/rules.php?v=microchess). ## 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.