Deployment

Gateway production deploys run as a dedicated stack (connect-gateway) and dedicated docker context (uebliche-gateway).

Runtime contract

Gateway is deployed as one service image that contains:

• watcher
• mcproxy

Control plane comes from Public API, not from a local dashboard.

Required/important environment

• CONNECT_API_BASE (default https://api.uebliche.net/v1)
• CONNECT_GATEWAY_CREDENTIALS_PATH (default /etc/minecraft/gateway-credentials.json)
• CONNECT_GATEWAY_NAME
• CONNECT_GATEWAY_REGION
• CONNECT_GATEWAY_NETWORK_ID
• CONNECT_GATEWAY_PUBLIC_HOST (optional fixed public host/IP)
• CONNECT_GATEWAY_MINECRAFT_PORT (default 25565)
• CONNECT_GATEWAY_CONNECT_PORT (default 9001)
• CONNECT_GATEWAY_HEARTBEAT_SECONDS (default 10)

CONNECT_GATEWAY_ID and CONNECT_GATEWAY_SECRET are optional. If missing, watcher auto-registers and persists credentials to CONNECT_GATEWAY_CREDENTIALS_PATH.

Open ports (production)

• 25565/tcp: Minecraft traffic
• 9001/tcp: Connect control + runtime metrics
• 80/tcp: health endpoints

Compose (single host)

cd gateway
docker compose -f compose.yml up -d --build

Swarm (recommended)

Use stack file:

• docker/stacks/gateway/docker-stack-gateway.yml

Example:

GATEWAY_DOCKER_CONTEXT=uebliche-gateway \
GATEWAY_IMAGE=registry.eu.uebliche.net:5000/uebliche/api \
GATEWAY_IMAGE_TAG=gateway-main-latest \
GATEWAY_STACK_NAME=connect-gateway \
docker --context "$GATEWAY_DOCKER_CONTEXT" stack deploy \
  -c docker/stacks/gateway/docker-stack-gateway.yml \
  "$GATEWAY_STACK_NAME"

Persistence

The stack uses a stable named volume for gateway credentials/routes:

• gateway_gateway-minecraft-config

This keeps gateway identity and route cache stable across stack updates/migrations.