Document Continuum-Servatrice dedicated server build and isolated MySQL hosting

doc/continuum-servatrice-hosting.md

@@ -0,0 +1,107 @@
+# Hosting Continuum-Servatrice
+
+**Continuum-Servatrice** is Continuumatrice's dedicated multiplayer server. It is built from the existing Servatrice C++ implementation, including accounts, lobbies, rooms, replays, game synchronization, TCP and WebSocket networking, and MySQL support. It also registers the three additional public pile zones: Limbo, Refuge, and Oblivion.
+
+You may run it alongside upstream Servatrice, but **never reuse the MTG server's database, schema, account tables, process name, or service configuration.**
+
+## Build client and server together
+
+On Linux with the existing development dependencies, from the repository root:
+
+```bash
+cmake -S . -B build --fresh -G Ninja \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DWITH_CLIENT=ON -DWITH_SERVER=ON -DWITH_ORACLE=OFF
+
+cmake --build build --target continuumatrice continuum-servatrice --parallel 16
+```
+
+Executable paths:
+
+- Client: `build/continuumatrice/continuumatrice`
+- Dedicated server: `build/continuum-servatrice/continuum-servatrice`
+
+The inherited source directories `cockatrice/` and `servatrice/` remain for source compatibility. The **binary build directories and targets are distinct**.
+
+`WITH_SERVER` is `ON` by default; use `-DWITH_CLIENT=OFF -DWITH_SERVER=ON` for a dedicated server-only build (e.g., on a Linux host). This project deliberately excludes the upstream Magic Oracle importer.
+
+## New independent MySQL schema
+
+The repository includes `servatrice/continuum-servatrice.sql`. This is **not** the old `servatrice.sql`: its table identifiers use the `continuum_servatrice_` prefix matching the fork server configuration. Do not apply these SQL scripts to a production MTG Servatrice database.
+
+Create a separate database and limited account using MySQL. The following is an example for local MySQL (choose a real, strong password and do not commit it):
+
+```sql
+CREATE DATABASE continuum_servatrice CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+CREATE USER 'continuum_servatrice'@'localhost' IDENTIFIED BY 'REPLACE_WITH_A_STRONG_PASSWORD';
+GRANT ALL PRIVILEGES ON continuum_servatrice.* TO 'continuum_servatrice'@'localhost';
+```
+
+Execute those statements as a MySQL administrator, for example `mysql -u root -p`. Then initialize the *empty* database:
+
+```bash
+mysql -u root -p continuum_servatrice < servatrice/continuum-servatrice.sql
+```
+
+This schema contains user and room tables; it is not the card catalogue. Card XML and images live on the client, and users joining the same game should use compatible Continuumatrice card databases.
+
+**Schema lifecycle:** The fork's new base SQL is isolated. Upstream schema migration scripts under `servatrice/migrations/` have not all been converted to the new prefix. Review/adapt each future migration against a **backup** of the fork database; never run the upstream migration scripts blindly on either product.
+
+## Configure server
+
+```bash
+mkdir -p ~/.config/continuum-servatrice
+cp servatrice/continuum-servatrice.ini.example ~/.config/continuum-servatrice/continuum-servatrice.ini
+chmod 600 ~/.config/continuum-servatrice/continuum-servatrice.ini
+```
+
+Edit the private INI file, at least:
+
+```ini
+[server]
+name=Continuum-Servatrice
+host=any
+port=4757
+websocket_host=any
+websocket_port=4758
+
+[database]
+type=mysql
+prefix=continuum_servatrice
+hostname=localhost
+database=continuum_servatrice
+user=continuum_servatrice
+password=REPLACE_WITH_YOUR_MYSQL_PASSWORD
+```
+
+Those are the **fork's example ports** (TCP 4757, WebSocket 4758), separate from the usual upstream 4747/4748. The server supports other ports. If you run multiple game servers on the same host, explicitly choose distinct bound ports and independently configured databases.
+
+To start in the terminal:
+
+```bash
+./build/continuum-servatrice/continuum-servatrice \
+  --config "$HOME/.config/continuum-servatrice/continuum-servatrice.ini" \
+  --log-to-console
+```
+
+A successful start requires database connectivity, a compatible schema, and available ports. Check the server's diagnostics rather than assuming a process that exits is running correctly.
+
+For Internet hosting, use firewall rules scoped to the ports you intend to expose, configure TLS / a secure reverse proxy for WebSockets, and avoid exposing MySQL directly to the Internet. The sample file has inherited settings for authentication, room permissions, email, and moderation; review them before public launch.
+
+## Client/server compatibility
+
+Continuumatrice supports standalone local games without a dedicated server. For remote games, use a **matching Continuum-Servatrice build**. Ordinary upstream Cockatrice servers don't define the `limbo`, `refuge`, or `oblivion` zone IDs.
+
+## Production verification
+
+- [ ] Client and server both compile from the same Git commit.
+- [ ] They create `build/continuumatrice` and `build/continuum-servatrice` with correct filenames.
+- [ ] Server starts with `--config` and can connect to the **independent** MySQL schema.
+- [ ] Account registration/authentication, room joining, game creation and reconnect work.
+- [ ] Cards move correctly into Limbo, Refuge and Oblivion for both players and after reconnect.
+- [ ] TCP and WebSocket connect on the configured ports.
+- [ ] No accesses to upstream MTG databases, profile directories, sockets, or HTTP update services.
+- [ ] No migration script alters a production database without backup/review.
+- [ ] Service hardening, logging, TLS and restart management are in place before public launch.
+
+**Status:** Committed source changes; dedicated server compilation, MySQL initialization, and runtime validation still need to be performed on the deployment system.