Getting Started

This guide walks you through setting up Passage for the first time. By the end, you’ll have a working Minecraft network entry point that authenticates and routes players to backend servers.

Prerequisites

A Minecraft backend server running version 1.20.5 or higher
Docker installed (recommended), or a Linux/macOS/Windows server for binary deployment
Basic knowledge of YAML configuration

Quick Start

Create configuration directory
Terminal window
```
mkdir -p passage/config
cd passage
```

Create configuration file

Create config/config.yaml with your backend server details:

address: "0.0.0.0:25565"

routes:
- hostname: ".*"
  status:
    type: fixed
    name: "My Minecraft Network"
    description: "\"Welcome to my server!\""
  discovery:
    type: fixed_discovery
    targets:
    - identifier: "lobby-1"
      address: "10.0.1.10:25565"  # Replace with your backend server

Start Passage

docker run -d \
  --name passage \
  -p 25565:25565 \
  -v $(pwd)/config:/app/config \
  ghcr.io/scrayosnet/passage:latest

Test the connection

Open Minecraft (version 1.20.5+) and add a server:
- Server Address: localhost:25565 (or your server IP)
You should see your configured MOTD and be able to connect.
Check logs
Terminal window
```
docker logs -f passage
```

Understanding the Configuration

Let’s break down what each section does:

Core Settings

address: "0.0.0.0:25565"

0.0.0.0 accepts connections from any network interface
25565 is the default Minecraft port

Routes

routes:
- hostname: ".*"

Each route matches a hostname pattern (regex). .* matches everything — useful for a single-server setup. For a multi-domain network, you’d use specific patterns like "lobby\\.example\\.net".

Status Adapter

  status:
    type: fixed
    name: "My Minecraft Network"
    description: "\"Welcome to my server!\""

Controls what players see in the server list. The description uses Minecraft’s JSON text format:

description: "{\"text\":\"Welcome!\",\"color\":\"gold\"}"

Discovery + Targets

  discovery:
    type: fixed_discovery
    targets:
    - identifier: "lobby-1"
      address: "10.0.1.10:25565"

Defines where to send players. Add multiple targets for load balancing:

  discovery:
    type: fixed_discovery
    targets:
    - identifier: "lobby-1"
      address: "10.0.1.10:25565"
      meta:
        players: "45"
    - identifier: "lobby-2"
      address: "10.0.1.11:25565"
      meta:
        players: "38"
    actions:
    - type: player_fill_strategy
      field: "players"
      max_players: 50

This fills servers to 50 players before moving to the next one. See Discovery Actions for all options.

Defaults You Get for Free

Without explicit configuration, each route uses:

Authentication: mojang (standard Mojang/Microsoft verification)
Localization: fixed with built-in English, Spanish, French, German, Chinese, and Russian messages

Configuration Examples

Multiple Lobbies with Load Balancing

address: "0.0.0.0:25565"

rate_limiter:
  duration: 60
  limit: 60

routes:
- hostname: "mc.example.net"
  status:
    type: fixed
    name: "BigNetwork"
    description: "\"500 players online!\""
  discovery:
    type: fixed_discovery
    targets:
    - identifier: "lobby-1"
      address: "10.0.1.10:25565"
      meta: { type: "lobby", players: "45" }
    - identifier: "lobby-2"
      address: "10.0.1.11:25565"
      meta: { type: "lobby", players: "38" }
    - identifier: "lobby-3"
      address: "10.0.1.12:25565"
      meta: { type: "lobby", players: "52" }
    actions:
    - type: meta_filter
      rules:
      - key: "type"
        op: equals
        value: "lobby"
    - type: player_fill_strategy
      field: "players"
      max_players: 50

DNS Discovery

routes:
- hostname: "mc.example.net"
  discovery:
    type: dns_discovery
    domain: "servers.example.net"
    record_type: srv
    actions:
    - type: player_fill_strategy
      field: "players"
      max_players: 50

Kubernetes with Agones

routes:
- hostname: "mc.example.net"
  status:
    type: http
    address: "http://status-service.minecraft/status"
    cache_duration: 30
  discovery:
    type: agones_discovery
    namespace: "minecraft"
    selectors:
    - matchLabels:
        game: "minecraft"
        type: "lobby"
    scheduling: "Packed"

See Kubernetes Guide for full setup.

Common Issues

”Can’t connect to server”

Check Passage is running: docker ps | grep passage
Verify port is listening: netstat -tuln | grep 25565
Check firewall allows port 25565

”Outdated client!” or “Outdated server!”

Ensure your Minecraft client is 1.20.5 or higher. Passage uses the transfer packet introduced in that version.

Player connects then immediately disconnects

Verify the backend server address in your config
Test backend connectivity: docker exec passage ping 10.0.1.10
Check backend server is running and accepting connections

Docker can’t reach backend on localhost

Docker Desktop (Mac/Windows): Use host.docker.internal instead of localhost
Linux: Use the Docker bridge IP (usually 172.17.0.1), or run with --network host

Debug Logging

Enable detailed logs to diagnose issues:

docker run -d \
  --name passage \
  -p 25565:25565 \
  -v $(pwd)/config:/app/config \
  -e RUST_LOG=debug \
  ghcr.io/scrayosnet/passage:latest

Troubleshooting Checklist

Before asking for help, verify:

Minecraft client version is 1.20.5 or higher
Backend server version is 1.20.5 or higher
Backend server is running and accessible from Passage
Port 25565 is not blocked by firewall
Configuration file is valid YAML
Backend address is correct (not localhost if using Docker)
Passage logs show no errors (docker logs passage)

Getting Help

Check logs: docker logs passage often reveals the problem
Community support: Visit GitHub Discussions
Bug reports: File issues at GitHub Issues