Set up Geyser and Floodgate on Velocity with Docker

NetherNet is now required: Bedrock 26.60 was released on 27 October 2026. According to Geyser, clients from 26.60 onward no longer connect over RakNet. Update Geyser and use transport: nethernet; switching back to RakNet does not fix current clients.

For iPhone/iPad issues and certificates, use the HTTPS guide for iOS and iPadOS.

Install Geyser on Velocity

The existing direct Geyser and Floodgate guide installs both plugins on one Paper server. This guide covers a different architecture: Velocity is already the public entry point for multiple backends, so Geyser runs on the proxy.

For this setup:

• install Geyser only on the proxy
• install Floodgate on the proxy for Bedrock account authentication
• add Floodgate to backends only when backend plugins need its API or related data
• make every backend compatible with the Java protocol version Geyser currently emulates

Check Geyser's supported-versions page before updating.

Step 1: Start from a working Velocity network

Complete these checks first:

• Java players can join Velocity and reach a Paper backend.
• Velocity modern forwarding works.
• Backends are not public.
• The proxy has a persistent /server mount.

Use the Velocity Compose guide and modern forwarding runbook if any of those statements is false.

Step 2: Add the proxy plugins and NetherNet mappings

The itzg/mc-proxy image can download plugin URLs into the proxy plugin directory. Add the official Geyser and Floodgate Velocity download endpoints and publish TCP signaling and UDP gameplay:

services:
  proxy:
    image: itzg/mc-proxy:latest
    ports:
      - "25565:25577/tcp"
      - "19132:19132/tcp"
      - "19132:19132/udp"
    environment:
      TYPE: VELOCITY
      MEMORY: 1G
      PLUGINS: "https://download.geysermc.org/v2/projects/geyser/versions/latest/builds/latest/downloads/velocity,https://download.geysermc.org/v2/projects/floodgate/versions/latest/builds/latest/downloads/velocity"
    volumes:
      - ./proxy:/server

The latest download endpoints are convenient for the first setup but change over time. For controlled production updates, pin reviewed plugin artifacts or preserve known-good JARs and update them as one tested operation.

Render the Compose file before starting:

docker compose config
docker compose up -d proxy
docker compose logs -f proxy

Confirm both plugins load without dependency or Java errors.

Step 3: Configure the Bedrock listener

Hosting on your PC or NAS? Find your public IP without renting a server explains checking from the home network and comparing the router WAN address. Do not advertise a local PC address as your public endpoint.

After the first start, open the Geyser configuration below the proxy's plugin directory and check:

bedrock:
  address: 0.0.0.0
  port: 19132
  clone-remote-port: false
  transport: nethernet
  webrtc-port: 0
  signaling:
    mode: builtin
    advertise-addresses:
      - "YOUR_PUBLIC_IP:19132"

transport: nethernet enables transport for current clients. 0.0.0.0 binds to container interfaces. Publish TCP and UDP 19132 and replace the advertised IP with your reachable public IP.

In the same generated Geyser configuration, locate auth-type and set it to floodgate. The surrounding section name can change between configuration versions, so edit the generated file instead of replacing it wholesale with an older example.

Restart the proxy after changing the configuration:

docker compose restart proxy
docker compose logs --tail=150 proxy

Step 4: Open the selected Bedrock ports end to end

For NetherNet, all four layers must allow both TCP signaling and UDP gameplay:

1. Geyser listens on TCP and UDP 19132 in the container.
2. Compose maps 19132:19132/tcp and 19132:19132/udp.
3. The Linux or Windows host firewall allows TCP and UDP 19132.
4. The router or cloud-provider firewall allows TCP and UDP 19132 to the host.

Do not replace the Java TCP rule with the Bedrock rule. Java and Bedrock use different transport paths here:

An SRV record used by Java does not remove the Bedrock port in this setup. Tell Bedrock players the explicit port.

Migrate an existing RakNet installation

Back up the generated Geyser configuration, apply the NetherNet settings above and add the TCP publication alongside UDP. Preserve Floodgate and backend settings. After Docker publication changes, use docker compose up -d, then fully restart the server/proxy. The NetherNet guide covers different port mappings, external signaling and current error reports.

Step 5: Validate from inside and outside

Check the Docker mapping:

docker compose port --protocol udp proxy 19132
docker compose logs --tail=150 proxy

For NetherNet, check TCP signaling with curl --fail --max-time 10 http://YOUR_PUBLIC_IP:19132/v1/join. Replace the placeholder with your public IP. If you receive server JSON, test a complete Bedrock join from outside your network. Use the NetherNet connection tests if joining fails.

The first successful login should reach the same backend selected by Velocity. Verify the player in both proxy and backend logs and confirm that their name/UUID behavior matches your Floodgate policy.

When backends need Floodgate too

Basic crossplay does not require Floodgate on every Paper server. Add it only when backend plugins need the Floodgate API, Bedrock skin handling, or Floodgate data.

The official extended procedure requires send-floodgate-data: true on the proxy and the same Floodgate key.pem on the trusted backends. That key enables Bedrock authentication and must never be published or sent to untrusted people. Transfer it as binary data, restrict file access, and rotate/rebuild the trust relationship if it leaks.

Troubleshooting

Next steps

• If Java routing is unreliable, use the Velocity backend runbook.
• Create a player-facing hostname with the Minecraft SRV generator, while keeping the Bedrock port explicit.
• Recheck Geyser supported versions before proxy or backend upgrades.

Sources

• Minecraft Bedrock 26.60 changelog
• HTTPS for NetherNet