Getting started

Getting started

Try it on one machine

mumbot ships a ready-made Docker Compose example with a standard Mumble server, mumpeer and the relay bot: mumbot examples/peer-with-relay. Follow its README; it takes a few minutes and needs only Docker and openssl.

Set it up for your community

You need a Linux host (x86_64 or aarch64) that the internet can reach on UDP and TCP 443, ideally with a DNS name such as relay.example.org, and a Mumble server where the relay bot can register.

1. Secret and config

mkdir mumpeer && cd mumpeer
echo "PEER_API_SECRET=$(openssl rand -hex 32)" > .env && chmod 600 .env
curl -fsSL -o mumpeer.toml https://raw.githubusercontent.com/Mumcord/mumpeer/main/mumpeer.example.toml

Edit mumpeer.toml and set public_host = "relay.example.org". Everything else has a good default. The secret never goes into the config.

2. Start mumpeer and the bot

docker-compose.yml:

services:
  mumpeer:
    image: ghcr.io/mumcord/mumpeer:0.3.0
    restart: unless-stopped
    environment:
      MUMPEER_API_SECRET: ${PEER_API_SECRET:?set PEER_API_SECRET in .env}
    ports: ["443:443/udp", "443:443/tcp"]
    volumes:
      - ./mumpeer.toml:/config/mumpeer.toml:ro
      - mumpeer-data:/var/lib/mumpeer

  mumbot:
    image: ghcr.io/mumcord/mumbot:0.6.0
    command: ["peer"]
    restart: unless-stopped
    network_mode: "service:mumpeer"   # reaches the API on 127.0.0.1:7480
    environment:
      MUMBOT_CONFIG: /config/bot.toml
      MUMBOT_PEER_API_SECRET: ${PEER_API_SECRET:?set PEER_API_SECRET in .env}
    volumes:
      - ./bot.toml:/config/bot.toml:ro
      - mumbot-data:/data

volumes:
  mumpeer-data:
  mumbot-data:

Write bot.toml as described in mumbot's peer documentation (Mumble server address, server certificate pin, [peer] api_url = "http://127.0.0.1:7480"), and register the bot on the Mumble server once. Then:

docker compose up -d
docker compose logs mumpeer | grep fingerprint

3. Check it

• The relay log shows relay fingerprint (SHA-256): …. You do not have to share it: the bot announces it.
• In Mumcord, the server info panel shows "Mumpeer relay: Yes" with the state "available".
• Two users share a screen while one of them hides their IP address (or a direct connection is impossible); the connection info shows "Via relay (UDP)".

Keep the mumpeer-data volume. It holds the relay key. A new key means a new fingerprint, and every user would see "The relay of this server changed".

Without Docker

Download mumpeer-<version>-linux-x86_64.tar.gz or mumpeer-<version>-linux-aarch64.tar.gz (static binary, any Linux distribution) from the releases, check it with sha256sum -c SHA256SUMS --ignore-missing, and run it as a systemd service: see Operating. Pin a version tag (0.3.0) in production; latest follows the newest stable release.

Next: Configuration · Operating · Security and privacy