Installation

Installation

BlueMapWebChat 4.7.0 · Minecraft 1.18–26.2 · Java 17 baseline

2. Requirements and Recommended Environment

Required:

• A Bukkit/Paper/Spigot-compatible Minecraft server in the conservative supported range 1.18 through 26.2
• Java 17 or newer as required by the selected Minecraft server version; BlueMapWebChat itself is compiled for Java 17
• Permission to install plugin JAR files

BlueMapWebChat 4.7.0 declares api-version: '1.18' and compiles against spigot-api:1.18.2-R0.1-SNAPSHOT. Minecraft 1.17 and older are not claimed by this release.

Optional integrations:

• BlueMap for an embedded map chat panel
• DiscordSRV for Discord integration
• ImageEmojis-Bero 1.9.0 for in-game rendering of BMChat emoji tokens
• Caddy or Nginx for a public HTTPS deployment

For public servers, do not expose port 8899 directly to the Internet. Bind BlueMapWebChat to 127.0.0.1:8899 and publish it through an HTTPS reverse proxy.

3. Installation and First Enable

1. Put the built JAR in the server plugins/ directory.
2. Start the server once.
3. Confirm that plugins/BlueMapWebChat/config.yml was created.
4. A newly generated configuration uses enabled: false.
5. Review URLs, storage, retention, authentication, and upload limits.
6. Enable the features you need and set enabled: true.
7. Restart the server or run /bmchat reload.

Safe initial state:

config-version: "4.7.0"
enabled: false

While disabled, the web service, chat forwarding, and cleanup tasks do not start. Administrators can still use /bmchat reload.

4. Configuration Upgrade and Migration Fragment

BlueMapWebChat never overwrites existing setting values during an update. It may reorder known top-level config blocks to match the bundled layout while preserving each block's current text, values, and custom comments.

BlueMapWebChat keeps the current full default configuration available as:

plugins/BlueMapWebChat/config-reference-4.7.0.yml

On startup/reload, known top-level config.yml blocks are reordered to the bundled 4.7.0 layout while each block's current text, values, and custom comments are preserved; unknown top-level blocks remain last in their original order.

It is an exact copy of the bundled default config.yml, including comments, and is useful for comparing very old configs. When config-version is missing or differs from the running plugin version, the plugin additionally creates:

plugins/BlueMapWebChat/config-migration-4.7.0.yml

Decision rules:

Physical config.yml state	Behavior
config-version is missing	Create the migration file with the target version marker even when there are zero other differences
config-version differs from the plugin version	Create or refresh the migration file with missing/changed settings and the target version marker
config-version matches the plugin version	Treat the configuration as reviewed, skip migration comparison, remove stale same-version migration guidance, and keep the full reference current

The file contains copy-ready YAML for:

• New settings missing from the installed configuration
• Defaults that changed while the installed value still matches the old default
• The target config-version review marker

Even when no other settings differ, the file is created with config-version so configuration version management remains explicit.

Counts and old/new value explanations are comments beginning with #. The live config.yml is not changed.

Upgrade procedure:

1. Open the migration fragment.
2. Merge the required blocks into the matching locations in config.yml.
3. Adjust server-specific and custom values.
4. After review, set:

config-version: "4.7.0"

When the version matches, future comparisons are skipped.