How to Set Up BlueMap on a Paper Server

Plan the map before installing BlueMap

BlueMap reads a Minecraft Java world, converts its generated chunks into 3D map data and serves that data through a browser application. On Paper, it can run as a plugin, keep maps updated as the world changes and host its own small web server. Treat those as two workloads: rendering consumes CPU and storage, while the web endpoint consumes a separate network port and serves files to visitors.

Record the Paper and Minecraft versions, the Java runtime used by the actual service, world folder names, free storage, available CPU cores and the extra TCP port assigned by the host. BlueMap's current installation guide requires Java 25 or newer and Java Edition worlds. Its current release page lists different artifacts and supported version ranges for Paper, Spigot and other platforms, so select the file whose target includes the live server instead of assuming that any BlueMap JAR fits every release.

Define the visible area and audience before the first render. BlueMap can only render chunks that Minecraft has already generated, but a large established world can still create a substantial first job and map dataset. Decide whether the map should be public, available only through a protected web path or kept private during setup. Back up the stopped Paper server, including worlds and plugin configuration, and preserve the current port and firewall state. The plugin review at /blog/install-plugins-paper-minecraft-server applies because BlueMap runs as server code and can read the world files.

• Confirm Paper, Minecraft, Java and the exact BlueMap artifact before maintenance.
• Reserve one additional TCP port for the built-in web server or plan a local reverse proxy.
• Measure free storage and choose which worlds or bounded areas should be visible.
• Take a complete stopped-server backup and keep a rollback copy of the network rules.

Install the matching Paper plugin

Download BlueMap from the project's official GitHub release or its project-controlled listing. Current releases provide separate platform artifacts, including a Paper JAR, so read the target table and changelog for the release you select. With Paper fully stopped, place exactly one compatible BlueMap JAR directly in the plugins directory. Remove an older active BlueMap JAR before starting, but retain it in the offline backup rather than beside the replacement.

Start Paper once and read the log from the beginning. BlueMap should create its configuration under plugins/BlueMap and preconfigure a map for each world it discovers. A generated directory is not enough: confirm that the plugin enabled, recognized the intended worlds and did not report a Java, platform or resource error.

Open plugins/BlueMap/core.conf, read the generated comments and set accept-download=true only after accepting the stated Mojang resource terms. BlueMap documents that it downloads Minecraft client resources from Mojang to build and texture the 3D models and cannot render without them. Then open webserver.conf and set port to the extra TCP allocation supplied by the host. The built-in server defaults to 8100, but a managed host must actually assign the chosen port; editing the number cannot create an allocation.

• Use the official release artifact whose platform and version range match the server.
• Install one JAR while Paper is stopped and verify the complete first startup log.
• Review the generated plugins/BlueMap configuration before changing defaults.
• Set accept-download deliberately and use a genuinely assigned TCP web port.

Limit the worlds and map detail deliberately

The maps directory contains one .conf file per configured map, commonly the Overworld, Nether and End. The filename without .conf becomes the map identifier used by commands and stored data. Inspect every generated file before rendering: world must point at the correct save folder, dimension must match the actual dimension and name should describe what visitors will see. Delete unwanted map configurations before they consume render time and storage.

Bound the product to the community's real exploration area. A render mask can limit which part of a world appears, and BlueMap removes map tiles that fall outside a changed mask. BlueMap still cannot invent ungenerated terrain; if a season needs a planned complete region, prepare and validate it with the measured workflow in /blog/pregenerate-paper-server-chunks before expecting the web map to show it.

Choose detail settings before committing to the first dataset. The map configuration documents perspective, flat and free-flight views plus the high-resolution layer. Disabling high resolution reduces render time and map storage substantially, but visitors lose full close-up 3D models. Changing several of these settings later can require a re-render. Start with the smallest view set that serves the map's purpose, keep the original generated configuration and record which settings would force a rebuild.

• Verify each map identifier, world path and dimension before rendering.
• Remove unwanted worlds and set a render mask for the intended playable area.
• Generate terrain separately and confirm its lighting before the map job begins.
• Select perspective, flat, free-flight and high-resolution layers from an explicit need.

Control the first render under real load

BlueMap renders asynchronously instead of running the conversion directly on Paper's main server thread, but both applications still share the machine. BlueMap's core configuration uses render-thread-count to control roughly how many CPU cores the render workers use and warns that higher values can affect host performance. Keep the value at or below available cores and leave headroom for Paper, the operating system and other services.

Use player-render-limit in plugin.conf when the map should pause once a chosen number of players is online. The documented default disables that pause, so set it intentionally when community play takes priority over map freshness. Schedule the initial conversion for a quiet window, postpone other heavy disk work, and watch Paper tick behavior, total CPU, storage growth and the BlueMap task queue together.

Run bluemap from the console, or /bluemap in game with the narrow bluemap.status permission, to see render status. bluemap tasks shows the queue, while bluemap stop and bluemap start pause and resume rendering persistently. Prefer a planned pause over killing Paper or deleting output during pressure. BlueMap then tracks changed chunks instead of repeatedly converting the whole map.

• Leave CPU headroom for Paper instead of maximizing render-thread-count.
• Pause rendering at a documented player threshold when play is the priority.
• Monitor tick health, CPU, disk use, task progress and errors during the first job.
• Use BlueMap's stop and start controls rather than interrupting files mid-write.

Publish the web map without exposing the server

For a direct test, allow the configured BlueMap TCP port through the container, host firewall and provider firewall, then open http://SERVER:PORT from another network. BlueMap's FAQ identifies 8100 TCP as the default and notes that the built-in server is plain HTTP. Expose only that assigned web port; players do not need the game panel, remote console, SSH, database or a broad port range to view a map.

For a public production address, put an HTTPS reverse proxy in front of the integrated server. BlueMap's reverse-proxy guide provides NGINX and Caddy examples for a subdomain or /map path. When the proxy runs on the same host, add ip="127.0.0.1" to webserver.conf so BlueMap listens only on loopback, then let the proxy own the public TLS endpoint. Test tile requests and live updates through the final hostname before closing the direct external rule.

Decide privacy at the application boundary. BlueMap does not provide authentication itself, and its plugin configuration enables live player markers by default. Review whether positions should be public, which conditions hide players and whether a protected reverse proxy is required. A hard-to-guess URL is not access control.

• Direct test: one assigned TCP port, plain HTTP and no unrelated services exposed.
• Production: HTTPS reverse proxy with BlueMap bound to loopback where possible.
• Privacy: review live player markers and add proxy authentication when required.
• Negative test: prove the former direct port is unreachable after proxy cutover.

Verify the map and fix missing tiles

Run an outside acceptance pass against the address visitors will use. The landing page and representative map tiles should return successfully, the browser should offer every intended world, and the map should survive a Paper restart. Visit known old and new locations, zoom into high resolution when enabled, and confirm that a small world change appears after Paper saves it.

If the page is unreachable, confirm that the log says the web server started, then verify the configured TCP port, listener, container mapping and each firewall layer. A 404 from the built-in server points toward accept-download or mismatched webroot values in webapp.conf and webserver.conf. If the page loads but the map is black or incomplete, check render progress, map freeze state, world path, dimension, BlueMap version compatibility and whether the chunks have actually been generated.

Lighting data can explain missing pregenerated or imported chunks. BlueMap normally omits chunks without generated light data. Its ignore-missing-light-data option can render them, but the project documents visual drawbacks including fully lit terrain and unreliable cave or night rendering. Treat that switch as a diagnosed workaround, not a first fix. Use bluemap troubleshoot for a failing map location, preserve the output and repair the world or configuration before purging valuable rendered data.

• Web failure: inspect listener, TCP allocation, proxy route and firewall layers.
• 404: verify accept-download and matching webroot configuration.
• Missing terrain: confirm progress, world, dimension, generation and lighting data.
• After each fix, retest one known coordinate through the final public address.

Operate and update BlueMap safely

Back up the BlueMap configuration and runtime data with the Paper service. Decide separately whether the rendered webroot belongs in every backup: it can be large, but omitting it increases recovery time because the map may need to render again. Record the map identifiers, masks, storage choice, web endpoint, proxy configuration and first-render duration so a restore or migration does not begin from guesswork.

Read every BlueMap release's upgrade instructions before replacing the JAR. The current v5.27 release, for example, tells some previous versions to delete the webroot index.html so BlueMap can update the web application, and older upgrade paths also require a new response-header setting. That is exactly why an update should be staged against a backup rather than reduced to swapping one file. Restart, inspect the full log, verify the web application and check representative tiles after each upgrade.

Keep a small operating baseline: Paper tick health during updates, render queue age, map storage growth, web response checks and certificate expiry. Freeze or pause a map before risky world maintenance and confirm updates resume afterward. More focused server guides are collected at /blog. If the measured render, storage or public web requirements exceed the current plan's allocations, compare the documented options at /pricing after the map scope has been reduced to what players actually use.