Multi Server Setup

Complete guide for configuring AnnouncementGUI across multiple servers in a network.

📋 Overview

AnnouncementGUI supports multi-server networks with real-time synchronization using MySQL. Create announcements on one server and they automatically sync to all others.

🎯 Key Concepts

Server IDs

Each server in your network has a unique identifier:

localServerId: "lobby"      # This server's ID

Target Selection

Announcements can target:

• Specific Server: e.g., "lobby", "survival", "creative"

• ALL Servers: Broadcasts network-wide

Synchronization

With MySQL storage:

• Create on one server → Appears on all

• Edit on any server → Updates everywhere

• Delete on any server → Removed from all

• Toggle on any server → Status syncs everywhere

🏗️ Network Architecture

Example Network

┌─────────────────────────────────────────┐
│          MySQL Database                 │
│      (Central Storage)                  │
└─────────────────────────────────────────┘
           ↕️          ↕️          ↕️
    ┌──────────┐ ┌──────────┐ ┌──────────┐
    │  Lobby   │ │ Survival │ │ Creative │
    │ Server   │ │  Server  │ │  Server  │
    └──────────┘ └──────────┘ └──────────┘

Components:

1. MySQL Database: Central storage for all announcements

2. Lobby Server: localServerId = "lobby"

3. Survival Server: localServerId = "survival"

4. Creative Server: localServerId = "creative"

📦 Prerequisites

Required

• 2+ Minecraft Servers: Paper 1.21+ or Folia

• MySQL Server: 5.7+ or MariaDB 10.2+

• Network Connectivity: All servers can reach MySQL

• AnnouncementGUI: Installed on all servers

Recommended

• Dedicated MySQL Server: Better performance

• Low Latency: Fast network between servers and MySQL

• Backup System: Regular MySQL backups

🚀 Setup Process

1

Install MySQL (Step 1)

Option A: Self-Hosted MySQL

Ubuntu/Debian:

Ubuntu/Debian

sudo apt update
sudo apt install mysql-server
sudo mysql_secure_installation

CentOS/RHEL:

CentOS/RHEL

sudo yum install mysql-server
sudo systemctl start mysqld
sudo mysql_secure_installation

Windows: Download and install from MySQL Downloads

2

Managed MySQL Service (Alternative to Step 1)

Popular options:

• AWS RDS

• Google Cloud SQL

• Azure Database for MySQL

• DigitalOcean Managed Databases

• Aiven

3

Create Database (Step 2)

Connect to MySQL:

Connect to MySQL

mysql -u root -p

Create database and user:

Create database and user

-- Create database
CREATE DATABASE minecraft_announcements;

-- Create dedicated user
CREATE USER 'announcegui'@'%' IDENTIFIED BY 'your_strong_password_here';

-- Grant privileges
GRANT ALL PRIVILEGES ON minecraft_announcements.* TO 'announcegui'@'%';

-- Apply changes
FLUSH PRIVILEGES;

-- Exit
EXIT;

Security Notes:

• Replace 'your_strong_password_here' with a strong password

• For production, consider using 'announcegui'@'specific_ip' instead of '%'

4

Configure Firewall (Step 3)

Allow MySQL access from server IPs.

Ubuntu/Debian (ufw):

ufw

sudo ufw allow from <server-ip> to any port 3306

CentOS/RHEL (firewalld):

firewalld

sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="<server-ip>" port protocol="tcp" port="3306" accept'
sudo firewall-cmd --reload

Test connection from each Minecraft server:

Test connection

mysql -h <mysql-host> -u announcegui -p minecraft_announcements

5

Install Plugin on All Servers (Step 4)

• Download AnnouncementGUI JAR

• Place in plugins/ folder on each server

• Start each server to generate configs

• Stop all servers

6

Configure Each Server (Step 5)

Edit plugins/AnnouncementGUI/config.yml on each server.

Lobby Server Configuration:

Lobby config.yml

# Unique ID for this server
localServerId: "lobby"

# List of all servers in network
servers:
  - "lobby"
  - "survival"
  - "creative"
  - "skyblock"

# Run ALL announcements on this server
enableAllServersAnnouncements: true

# Check for changes every 10 seconds
changePollingIntervalSeconds: 10

# MySQL storage configuration
storage:
  type: mysql
  mysql:
    host: "192.168.1.100"  # Your MySQL server IP
    port: 3306
    database: "minecraft_announcements"
    username: "announcegui"
    password: "your_strong_password_here"
    params: "useSSL=false&serverTimezone=UTC"

Survival Server Configuration:

Survival config.yml

# Unique ID for this server
localServerId: "survival"

# List of all servers in network (same as lobby)
servers:
  - "lobby"
  - "survival"
  - "creative"
  - "skyblock"

# Run ALL announcements on this server
enableAllServersAnnouncements: true

# Check for changes every 10 seconds
changePollingIntervalSeconds: 10

# MySQL storage configuration (same as lobby)
storage:
  type: mysql
  mysql:
    host: "192.168.1.100"
    port: 3306
    database: "minecraft_announcements"
    username: "announcegui"
    password: "your_strong_password_here"
    params: "useSSL=false&serverTimezone=UTC"

Other Servers:

• Same servers list on all servers

• Same MySQL configuration on all servers

• Different localServerId for each server

• Adjust enableAllServersAnnouncements per server needs

7

Start All Servers (Step 6)

1. Start all servers

2. Check console logs for:

Expected logs

[AnnouncementGUI] Initializing AnnouncementGUI...
[AnnouncementGUI] Using lightweight announcement change polling...

1. Check for any MySQL connection errors

8

Test Synchronization (Step 7)

1. Connect to Lobby Server

2. Run /announcegui

3. Create a test announcement:

   • Name: "Test Sync"

   • Message: "Testing multi-server sync"

   • Interval: 300

   • Server: "ALL"

   • Save

4. Wait 10-15 seconds (polling interval)

5. Connect to Survival Server

6. Run /announcegui

7. Click "Edit" - The "Test Sync" announcement should appear!

8. Edit on Survival - Change message

9. Check on Lobby - Changes should sync within 10-15 seconds

⚙️ Configuration Options

Polling Interval

Controls how often servers check for changes:

changePollingIntervalSeconds: 10  # Check every 10 seconds

Recommendations:

Network Size	Polling Interval	Rationale
2-5 servers	5-10 seconds	Fast sync, low overhead
5-10 servers	10-15 seconds	Balanced
10-20 servers	15-30 seconds	Reduce MySQL load
20+ servers	30-60 seconds	Minimize database queries

Trade-offs:

• Lower values: Faster sync, more database queries

• Higher values: Slower sync, fewer database queries

Enable/Disable ALL Announcements

Control whether a server runs network-wide (ALL) announcements:

enableAllServersAnnouncements: true  # Run ALL announcements

Use Cases:

Enable on Hub/Lobby:

localServerId: "lobby"
enableAllServersAnnouncements: true  # Players see network announcements

Disable on Minigame Servers:

localServerId: "bedwars"
enableAllServersAnnouncements: false  # Only bedwars-specific announcements

MySQL Connection Parameters

Customize MySQL connection:

params: "useSSL=false&serverTimezone=UTC&maxPoolSize=10"

Common Parameters:

Parameter	Purpose	Example
useSSL	Enable/disable SSL	useSSL=true
serverTimezone	Set timezone	serverTimezone=UTC
maxPoolSize	Connection pool size	maxPoolSize=10
autoReconnect	Auto-reconnect	autoReconnect=true
characterEncoding	Character encoding	characterEncoding=utf8

Production Example:

params: "useSSL=true&requireSSL=true&serverTimezone=UTC&maxPoolSize=20&autoReconnect=true"

🎯 Server Targeting Strategies

Specific Server Announcements

Goal: Different announcements per server.

Configuration:

• Each server has unique localServerId

• Create announcements targeting specific servers

Example:

Announcement 1:
- Name: "Lobby Welcome"
- Target: "lobby"
- Message: "Welcome to the lobby!"

Announcement 2:
- Name: "Survival Rules"
- Target: "survival"
- Message: "Follow survival rules!"

Announcement 3:
- Name: "Creative Tips"
- Target: "creative"
- Message: "Be creative!"

Result:

• Lobby only shows "Lobby Welcome"

• Survival only shows "Survival Rules"

• Creative only shows "Creative Tips"

Network-Wide Announcements

Goal: Same announcements everywhere.

Configuration:

• All servers have enableAllServersAnnouncements: true

• Create announcements targeting "ALL"

Example:

Announcement 1:
- Name: "Network Welcome"
- Target: "ALL"
- Message: "Welcome to our network!"

Result:

• All servers show the same message

Hybrid Approach

Goal: Mix of specific and network-wide.

Configuration:

• All servers have enableAllServersAnnouncements: true

• Mix of specific and ALL targets

Example:

Announcement 1:
- Name: "Vote Reminder"
- Target: "ALL"
- Message: "Vote for rewards!"

Announcement 2:
- Name: "Survival Events"
- Target: "survival"
- Message: "Join survival events!"

Announcement 3:
- Name: "Creative Contests"
- Target: "creative"
- Message: "Creative building contest!"

Result:

• All servers show "Vote Reminder"

• Survival shows "Vote Reminder" + "Survival Events"

• Creative shows "Vote Reminder" + "Creative Contests"

Hub-Only Network Announcements

Goal: Network announcements only in hub.

Configuration:

• Hub: enableAllServersAnnouncements: true

• Game servers: enableAllServersAnnouncements: false

Example:

Hub Config:
enableAllServersAnnouncements: true

Game Server Configs:
enableAllServersAnnouncements: false

Result:

• Hub shows ALL + lobby-specific announcements

• Game servers only show game-specific announcements

🔧 Advanced Configurations

Multiple Database Setups

Use Case: Separate databases for different server groups.

Setup:

Group 1 (Survival Network):
- survival-1, survival-2, survival-3
- Database: survival_announcements

Group 2 (Creative Network):
- creative-1, creative-2
- Database: creative_announcements

Configuration:

Survival Servers:

localServerId: "survival-1"  # or survival-2, survival-3
servers:
  - "survival-1"
  - "survival-2"
  - "survival-3"
storage:
  type: mysql
  mysql:
    database: "survival_announcements"
    # ... other settings

Creative Servers:

localServerId: "creative-1"  # or creative-2
servers:
  - "creative-1"
  - "creative-2"
storage:
  type: mysql
  mysql:
    database: "creative_announcements"
    # ... other settings

Geographic Distribution

Use Case: Servers in different regions.

Considerations:

• Latency: Higher ping to MySQL

• Polling Interval: Increase if high latency

• Replication: Consider MySQL master-slave replication

Example Setup:

US Region:
- MySQL Primary: us-mysql.example.com
- Servers: us-lobby, us-survival

EU Region:
- MySQL Replica: eu-mysql.example.com
- Servers: eu-lobby, eu-survival

High Availability

Use Case: Ensure uptime even if MySQL fails.

Strategy:

1. MySQL Replication: Master-slave setup

2. Failover: Automatic failover to replica

3. Load Balancing: Distribute queries

Tools:

• MySQL Master-Slave Replication

• ProxySQL

• HAProxy

• Kubernetes with MySQL Operator

📊 Monitoring and Maintenance

Monitoring Checklist

• MySQL server uptime

• MySQL connection count

• Announcement sync delay

• Database query performance

• Network latency between servers and MySQL

• Plugin errors in server logs

Maintenance Tasks

Weekly:

• Check MySQL connection logs

• Verify announcements syncing

• Review server console for errors

Monthly:

• Optimize MySQL tables

• Review and clean old announcements

• Check database size

• Update MySQL credentials if needed

Quarterly:

• Full MySQL backup

• Test disaster recovery

• Review polling intervals

• Update plugin versions

MySQL Optimization

Optimize Tables:

Optimize tables

USE minecraft_announcements;
OPTIMIZE TABLE announcements;
OPTIMIZE TABLE announcement_changelog;

Check Table Status:

Table status

SHOW TABLE STATUS FROM minecraft_announcements;

View Active Connections:

Processlist

SHOW PROCESSLIST;

🐛 Troubleshooting

Issue: Announcements not syncing

Symptoms:

• Create on Server A, doesn't appear on Server B

Diagnosis:

1. Check changePollingIntervalSeconds - wait at least that long

2. Check MySQL connectivity from both servers

3. Check console logs for errors

4. Verify same database in configs

Solutions:

# Test MySQL connection from each server
mysql -h <mysql-host> -u announcegui -p minecraft_announcements

# Check config.yml
- Same MySQL host, database, username, password
- Correct localServerId for each server
- Same server list on all servers

# Check logs
- Look for "Failed to connect to MySQL"
- Look for "Failed to poll changes"

Issue: Slow synchronization

Symptoms:

• Changes take minutes to sync

Causes:

• High polling interval

• Network latency

• MySQL performance issues

Solutions:

1. Reduce polling interval:

changePollingIntervalSeconds: 5

1. Check network latency:

ping <mysql-host>

1. Optimize MySQL:

OPTIMIZE TABLE announcements;
OPTIMIZE TABLE announcement_changelog;

Issue: MySQL connection errors

Symptoms:

• "Failed to connect to MySQL" in console

Solutions:

1. Verify credentials:

mysql -h <host> -u <username> -p<password> <database>

1. Check firewall:

telnet <mysql-host> 3306

1. Verify MySQL user permissions:

SHOW GRANTS FOR 'announcegui'@'%';

1. Check MySQL max connections:

SHOW VARIABLES LIKE 'max_connections';

Issue: Duplicate announcements

Symptoms:

• Same announcement appears multiple times

Causes:

• Duplicate server IDs

• Import with duplicate IDs

Solutions:

1. Verify unique server IDs: Each server must have different localServerId

2. Clean database:

Find duplicates

-- Backup first!
-- Then check for duplicates
SELECT id, name, COUNT(*) 
FROM announcements 
GROUP BY id, name 
HAVING COUNT(*) > 1;

Issue: Server-specific announcements not working

Symptoms:

• Announcement targeting "survival" shows on all servers

Solutions:

1. Verify target: Check announcement target is correct

2. Verify localServerId: Check each server's localServerId

3. Check database: Verify stored targetServerId in database

📋 Best Practices

1

Consistent Configuration

Keep configs synchronized:

• Same server list across all servers

• Same MySQL credentials

• Consistent polling intervals

2

Document Server IDs

Maintain a document listing:

• Server ID → Server name → IP/hostname

Example:

lobby → Lobby Server → mc1.example.com
survival → Survival Server → mc2.example.com

3

Test Before Production

Set up test environment:

• Test MySQL setup

• Test synchronization

• Test failover

• Then deploy to production

4

Monitor Sync Delays

Track how long sync takes:

• Create test announcement

• Note time

• Check other servers

• Adjust polling interval if needed

5

Secure MySQL

• Use strong passwords

• Limit user privileges

• Enable SSL if over internet

• Use firewall rules

• Regular security audits

6

Regular Backups

Backup strategy:

• Daily automated MySQL backups

• Weekly full backups

• Keep backups for 30 days

• Test restore process

7

Naming Conventions

Use clear server IDs:

✅ Good: lobby, survival, creative, skyblock
❌ Bad: server1, srv2, test, abc

---

Related Documentation:

• Configuration Guide - Detailed configuration

• Installation Guide - Installation steps

• Troubleshooting - Common issues

• Features Guide - Feature overview