Ceremony Integration (NATS)

Ceremony Integration

Journey uses Ceremony’s NATS messaging system to enable cross-server functionality for global tasks and parties. This guide explains how to set up NATS for your server network.

What is NATS?

NATS is a lightweight messaging system that allows your servers to communicate in real-time. Journey uses Ceremony’s NATS integration to sync:

• Global task progress across all servers
• Global task start/stop commands
• Party invites and updates across servers
• Party task progress for cross-server parties

Prerequisites

• Ceremony mod installed on all servers
• Journey mod installed on all servers
• A NATS server (can be on a separate machine or one of your Minecraft servers)

---

Setting Up NATS

Step 1: Install a NATS Server

Choose one of these options:

Option A: Docker (Recommended)

docker run -d --name nats -p 4222:4222 -p 8222:8222 nats:latest

Ports:

• 4222 - Client connections
• 8222 - HTTP monitoring

Option B: Standalone Binary

1. Download from https://nats.io/download/
2. Run the server:

   ./nats-server

Step 2: Configure Ceremony

Edit config/ceremony/config.json on each Minecraft server:

{
  "nats": {
    "enabled": true,
    "url": "nats://localhost:4222",
    "cluster_name": "my-network",
    "server_name": "survival"
  }
}

Configuration Options:

• enabled - Set to true to enable NATS messaging
• url - URL of your NATS server (use your NATS server’s IP/hostname)
• cluster_name - A unique identifier for your server network (must be the same on all servers)
• server_name - A unique name for this specific server (e.g., “survival”, “creative”, “skyblock”)

---

Multi-Server Setup Example

Network Layout

• NATS Server: 192.168.1.100:4222
• Servers: Survival, Creative, Skyblock

Survival Server

File: config/ceremony/config.json

{
  "nats": {
    "enabled": true,
    "url": "nats://192.168.1.100:4222",
    "cluster_name": "pixelmon-network",
    "server_name": "survival"
  }
}

Creative Server

File: config/ceremony/config.json

{
  "nats": {
    "enabled": true,
    "url": "nats://192.168.1.100:4222",
    "cluster_name": "pixelmon-network",
    "server_name": "creative"
  }
}

Skyblock Server

File: config/ceremony/config.json

{
  "nats": {
    "enabled": true,
    "url": "nats://192.168.1.100:4222",
    "cluster_name": "pixelmon-network",
    "server_name": "skyblock"
  }
}

Key Points:

• All servers use the same NATS URL
• All servers use the same cluster_name
• Each server has a unique server_name

---

Verification

Check Server Logs

After starting your Minecraft servers, check the logs for:

[Ceremony] Successfully connected to NATS server at nats://192.168.1.100:4222
[Ceremony] NATS cluster: pixelmon-network, server: survival

Verify Connection

If you see connection errors:

1. NATS server is running - Check with docker ps (Docker) or process manager
2. Port 4222 is accessible - Check firewall rules
3. URL is correct - Verify IP/hostname in config
4. NATS server is reachable - Test with telnet 192.168.1.100 4222

---

How Cross-Server Sync Works

Global Tasks Sync

When you run /globaltask start journey:example_task on the Survival server:

1. Survival server broadcasts a GlobalTaskStartPacket via NATS
2. All connected servers receive the packet and start the task locally
3. Boss bars appear for all players on all servers
4. Any player action on any server contributes to the shared progress
5. Progress updates are broadcast via GlobalTaskProgressPacket
6. All servers update their boss bars in real-time

Party Sync

When a party is created:

1. Party data is stored on the server where it was created
2. Party invites are sent via NATS to players on other servers
3. Party updates (member join/leave/kick) sync across all servers
4. Task progress from any party member on any server is shared with all party members

---

NATS Monitoring

HTTP Monitoring Interface

Access the NATS monitoring interface at:

http://your-nats-server:8222

Available endpoints:

• /varz - General server information
• /connz - Connection information
• /subsz - Subscription information
• /routez - Route information

Command Line Monitoring

If using NATS CLI tools:

# List servers
nats server list

# Monitor activity
nats server request

# View subscriptions
nats subscription list

---

Troubleshooting

Global Tasks Not Syncing

Symptoms:

• Global tasks start on one server but not others
• Progress doesn’t sync across servers

Check:

1. NATS is running and accessible from all servers
2. All servers have matching cluster_name in Ceremony config
3. global_tasks_enabled: true in Journey config
4. Server logs show successful NATS connection
5. No firewall blocking port 4222

Test:

• Start a global task on Server A
• Check logs on Server B for “Started global task from network: …”
• If no message appears, NATS messages aren’t reaching Server B

Party Invites Not Working Cross-Server

Symptoms:

• Players can’t invite players on other servers
• Party commands fail for cross-server operations

Check:

1. NATS is configured and connected
2. party_enabled: true in Journey config
3. Players have correct permissions
4. Target player is actually online on the other server
5. Check server logs for NATS errors

Connection Errors

Error: Failed to connect to NATS server

Solutions:

1. Verify NATS server is running
2. Check firewall allows port 4222
3. Verify url in config is correct
4. Test connectivity with telnet <ip> 4222

Error: Authentication failed

Solutions:

1. If NATS has authentication, add credentials to URL:

   "url": "nats://username:password@192.168.1.100:4222"

---

Performance Considerations

NATS Server Resources

Recommended Specs:

• CPU: 1-2 cores
• RAM: 512MB - 1GB
• Network: Low latency connection to Minecraft servers

Message Throughput

• Global tasks generate messages on every player action that matches filters
• Parties generate messages when any member makes task progress
• For large networks (100+ players), monitor NATS message throughput

Optimization Tips

1. Dedicated NATS server - Don’t run NATS on the same machine as Minecraft for production
2. Low latency network - Keep NATS server on the same network as Minecraft servers
3. Monitor message rate - Use NATS monitoring to track messages/second
4. Limit concurrent global tasks - Max 2-3 active global tasks recommended
5. Optimize task filters - Complex MoLang filters execute on every event

---

Security

Network Security

✅ Internal network only - Don’t expose NATS port 4222 to the internet

✅ Firewall rules - Allow only your Minecraft servers to connect

✅ Authentication - Enable NATS authentication for production:

# Start NATS with authentication
nats-server --user admin --pass secretpassword

Update Ceremony config:

{
  "nats": {
    "url": "nats://admin:secretpassword@192.168.1.100:4222"
  }
}

TLS Encryption

For sensitive data, enable TLS:

# Start NATS with TLS
nats-server --tls --tlscert=server.crt --tlskey=server.key

Update Ceremony config:

{
  "nats": {
    "url": "nats://192.168.1.100:4222",
    "tls": true
  }
}

---

Best Practices

Infrastructure

✅ Dedicated NATS server - Separate from Minecraft servers

✅ Reliable networking - Low latency, high availability network

✅ Monitor NATS - Use monitoring interface to track health

✅ Backup configs - Keep Ceremony configs in version control

Failover

What happens if NATS goes down?

• Global tasks continue working locally on each server
• Cross-server sync stops until NATS reconnects
• Parties continue working locally on their home server
• When NATS reconnects, sync resumes automatically

Recommendations:

1. Run NATS on a reliable machine with high uptime
2. Consider NATS clustering for high availability (advanced)
3. Monitor NATS health and set up alerts

---

Related Systems

• Global Tasks - Server-wide collaborative tasks
• Party System - Group task sharing
• Configuration - Journey configuration options