Velocity

Minecraft Velocity proxy container for Grounds.gg infrastructure

Use the Velocity image when you need a shared Minecraft proxy container for Grounds infrastructure.

This image is designed for Kubernetes-based environments and consistent local and production deployments.

Registry

ghcr.io/groundsgg/containers/velocity

Usage

Pull the image locally:

docker pull ghcr.io/groundsgg/containers/velocity:latest

Use it as a base image in your Dockerfile:

FROM ghcr.io/groundsgg/containers/velocity:latest

Verify that the image is available locally with docker image inspect ghcr.io/groundsgg/containers/velocity:latest.

Static Backends

The image bundles plugin-agones, which can register non-Agones backends through GROUNDS_STATIC_SERVERS. In production, keep this value in one dedicated Helm chart as an immutable, versioned ConfigMap. Every Java Velocity proxy must source the same required key:

env:
  - name: GROUNDS_STATIC_SERVERS
    valueFrom:
      configMapKeyRef:
        name: velocity-static-servers-v1
        key: GROUNDS_STATIC_SERVERS

The chart owns a ConfigMap such as velocity-static-servers-v1, with immutable: true, the GROUNDS_STATIC_SERVERS key, and the Helm annotation helm.sh/resource-policy: keep. Its value is a comma-separated list of name=host:port entries. To change the list, create a new versioned ConfigMap, update every proxy reference, and roll out the proxies. Keep the prior version until that rollout finishes, then garbage-collect it deliberately. Do not duplicate a literal value in each production proxy chart.

For local development, a literal environment value remains convenient:

env:
  - name: GROUNDS_STATIC_SERVERS
    value: "buildserver=buildserver:25565"

After the proxies restart, permitted players can connect with /server buildserver. See the Velocity plugin reference for the parser, startup failure behavior, and forwarding requirements.

The backend must use modern Velocity forwarding and the same forwarding secret as the proxies. Static discovery does not configure Paper or make an offline-mode backend safe to expose publicly.

Documentation

• Configure discovery and forwarding with the Velocity plugin reference.
• Review the velocity directory in the container repository.