Skip to content

README.md

Latest commit

 

History

History
110 lines (73 loc) · 3.85 KB

README.md

File metadata and controls

110 lines (73 loc) · 3.85 KB

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.