SyncServer

A lightweight server that keeps Minecraft schematics in sync across multiple game servers. Each group of servers that should share the same schematics connects to a named pool on this broker.

Example: three practice servers and three build-team servers on the same broker — practice servers use the practice pool, build-team servers use the build-team pool. Each pool is completely isolated.

---

Requirements

• Python 3.10 or newer
• Internet access to install packages (one-time)

---

Setup

1. Install dependencies

pip install -r requirements.txt

2. Create your config file

Copy the example and edit it:

cp conf.txt.example conf.txt

Open conf.txt and set at minimum:

Setting	What it does
host	Address to listen on. 0.0.0.0 means all interfaces.
port	TCP port (default 8756).
api_key	Shared secret. Change this. All clients must send this key.
data_dir	Where schematics and backups are stored (default data/).
backup_hours	How often to create a zip backup (default 12).

Every setting can also be set via environment variable (SCHEMSYNC_HOST, SCHEMSYNC_PORT, SCHEMSYNC_API_KEY, SCHEMSYNC_DATA, SCHEMSYNC_BACKUP_HOURS). Environment variables take priority over conf.txt.

To use a config file at a custom path, set SCHEMSYNC_CONF=/path/to/conf.txt.

3. Start the broker

python app.py

The server starts and is ready immediately. No database, no migrations.

---

Pools

A pool is a named group of clients that share one set of schematics. Pools are created automatically the first time any authenticated request uses that name — no pre-registration needed.

Pool names may only contain letters, numbers, hyphens, and underscores (max 64 characters). Examples: practice, build-team, survival-1.

Schematics are stored separately per pool:

data/
  schematics/
    practice/
    build-team/
  backups/
    practice/
    build-team/

---

API Overview

All /v1/ endpoints require the X-API-Key header matching the configured api_key.

Method	Path	Description
GET	/health	Status check. Returns config path and list of existing pools. No auth required.
GET	/v1/{pool}/list	List all schematics in a pool (path, size, last-modified).
GET	/v1/{pool}/file/{path}	Download a schematic file. Response includes X-Mtime-Ms header (ms since epoch).
POST	/v1/{pool}/upload	Upload or overwrite a schematic. Multipart form: path + file. Optional headers: X-Client-Mtime-Ms (preserve source mtime), X-Skip-Ws-Broadcast: 1 (suppress WS notification).
POST	/v1/{pool}/notify/repo-resync	Tell all connected clients in the pool to do a full re-sync.
POST	/v1/{pool}/hook/plugin	Plugin webhook: JSON body {"path": "..."}, notifies connected clients that a file changed.
WS	/v1/{pool}/ws?token=KEY	WebSocket for real-time change notifications. Closes with code 4400 on invalid pool name, 4401 on bad token.

WebSocket events

Connected clients receive JSON messages when schematics change:

{ "event": "schematic_updated", "path": "region/spawn.schem" }
{ "event": "repo_resync" }

---

Backups

The broker automatically zips all schematics per pool on the configured interval and saves them to data/backups/<pool>/schematics-YYYYMMDD-HHMMSS.zip. Backups run in the background and never interrupt normal operation. Minimum interval is 1 hour regardless of the configured value.

---

Security notes

• Keep conf.txt private — it contains your API key. It is excluded from version control by .gitignore.
• If you expose the broker to the internet, put it behind a reverse proxy (nginx, Caddy) with TLS.
• Pool creation is gated behind the master API key, so only authorized clients can create new pools.