Skip to content
+Mesh
Browse documentation: Operations

Mesh relay

Operations

Monitor, update, back up, restore and troubleshoot a production Mesh relay container.

Logs and lifecycle

bash
docker logs -f --tail 100 mesh-relay
docker restart mesh-relay
docker inspect mesh-relay

Monitor disk usage for the Docker volume as well as CPU, memory and container restarts. The current image does not define a Docker health check.

Update latest

The latest tag follows the most recent successful image build. Pulling it does not update an already running container; recreate the container while retaining the same /data volume.

With Compose:

bash
docker compose pull relay
docker compose up -d relay
docker image prune

With docker run, pull the image, remove the old container and rerun the complete command from the installation guide with the same volume and arguments:

bash
docker pull ghcr.io/mockingmagician/mesh-relay:latest
docker rm -f mesh-relay

Do not remove mesh-relay-data during an update. Back it up before deploying a new image because storage and protocol formats are still experimental.

Back up the relay

Stop the relay to obtain a consistent snapshot, then archive the named volume into the current directory:

bash
docker stop mesh-relay

docker run --rm \
  -v mesh-relay-data:/data:ro \
  -v "$PWD":/backup \
  alpine \
  tar czf /backup/mesh-relay-backup.tar.gz -C /data .

docker start mesh-relay

Store the archive securely. It contains the relay databases and persistent state.

Restore a backup

Restore only into an empty volume while the relay is stopped:

bash
docker volume create mesh-relay-data

docker run --rm \
  -v mesh-relay-data:/data \
  -v "$PWD":/backup:ro \
  alpine \
  tar xzf /backup/mesh-relay-backup.tar.gz -C /data

Then recreate the relay with the same public host, origins and network.

Firewall

Allow both transports on the chosen external port. For the default port, with UFW:

bash
sudo ufw allow 41234/tcp
sudo ufw allow 41234/udp

Apply equivalent rules in the hosting provider firewall and any upstream router or NAT gateway.

Troubleshooting

The container starts but peers cannot reach it

  • Check that --host is a public IPv4 address or DNS name, without http:// or a path.
  • Confirm that --external-port matches the Docker host port mapped to internal port 41234.
  • Confirm the chosen inbound TCP and UDP port from outside the local network.
  • Check port forwarding if the host is behind NAT.
  • Do not use an IPv6 literal, localhost, 0.0.0.0 or a private LAN address as the advertised host.

The relay does not join the public network

  • Confirm both origins are passed as one comma-separated value.
  • Check outbound connectivity to 88.186.133.102:12000 and 88.186.133.102:12001.

The image does not run

The published image currently targets Linux amd64. An ARM host requires emulation and is not an officially supported deployment.

Disk usage keeps growing

The current runtime does not schedule automatic age-based deletion of message envelopes. Delivered and undelivered encrypted envelopes and their routing metadata may remain in relay.db; monitor the volume and plan capacity accordingly.