Local development stack

Everything runs in Docker, from dev/: PostgreSQL, Redis, server-service, Velocity 4.3.1 and Paper 26.3 with the GrayCore plugins mounted from target/. Connect with a Minecraft client to localhost:25565.

Quick start

cd dev
./dev.sh up          # Windows: .\dev.ps1 up   (builds with Maven, then starts the stack)
./dev.sh logs paper  # follow a service

Requirements: Docker, JDK 25 and Maven (the plugins are built on the host).

Command	What it does
up	Build, then start Velocity and one Paper server (dev-gens-1).
multi	Same, plus a second Paper server (dev-gens-2) to test server switching, player locks and crashes.
reload	Rebuild and restart Velocity and Paper to pick up new plugin jars.
psql	Open a SQL shell on the dev database.
console <service> <command>	Type a command in a server console, e.g. ./dev.sh console paper op YourName.
logs [service]	Follow the logs.
reset	Stop everything and wipe dev/data/ (the database is recreated by Liquibase on the next start).

Layout

• docker-compose.yml: the stack. Every value has a working default; copy .env.example to .env to override.
• config/: committed templates, copied into the servers on first start (edits made in data/ are never overwritten). ${CFG_*} placeholders are filled from the compose environment.
• data/: git-ignored persistent data (PostgreSQL, Redis, Paper and Velocity folders).

Service	What it is
velocity	The proxy, the only one exposed (localhost:25565).
paper, paper-2	The game servers dev-gens-1 and dev-gens-2 (the second with multi).
server-service	The registry of game servers.
postgres, redis	The shared storage.
resource-packs	Serves the resource packs published by the RPG sample on localhost:8088.

Admin and debug mode

The admin group (every plugin permission, including graycore.commands.debug) is created the first time a Paper server starts. Give it to yourself from the console, then use the commands in game:

./dev.sh console paper grayperms player add-group YourName admin

/debug on then shows how your profile is loaded and saved, and which servers the proxy considered when routing you. See Administration.

Notes

• The console helper runs mc-send-to-console as user 1000, as the image requires: docker compose exec paper mc-send-to-console ... without -u 1000 fails with "Exec needs to be run with user ID 1000".
• Velocity runs in online mode: you need a real Minecraft account. Only Velocity is exposed, not the game servers.
• Third-party plugins (FastAsyncWorldEdit, WorldGuard, PlaceholderAPI, TAB, BetterModel) are downloaded from Modrinth when a server starts. FastAsyncWorldEdit and WorldGuard are pinned to versions that work together: a newer pair once stopped WorldGuard, and GrayCorePaper with it. Move both at once, and check a server starts.
• Paper and Velocity register through server-service: there are no static servers in velocity.toml.
• ./dev.sh psql, then select name, lock, lock_expires_at from players;, shows which server owns which player.