MySQL Setup

BadgerPanel uses MySQL for two purposes:

1. Panel database -- The panel's own MySQL instance stores all application data (users, servers, billing, configuration). This is included in the Docker Compose stack and configured automatically.

2. Game server databases -- Many games (especially Minecraft with plugins) need their own MySQL databases. BadgerPanel can provision databases on external MySQL hosts and provide connection details to game servers.

This guide covers setting up external MySQL database hosts for game server databases.

How Game Server Databases Work

When a user requests a database for their game server:

1. The panel connects to a pre-configured database host (an external MySQL server)
2. Creates a new database with a generated name
3. Creates a user with a secure random password
4. Grants the user full access to that database only
5. Displays connection details (host, port, database, username, password) in the server dashboard

Users can then configure their game server plugins to connect using these credentials.

Setting Up a Database Host

Option A: Dedicated MySQL Server

For production environments, run a separate MySQL server for game server databases. This isolates game server database load from the panel's database.

1. Install MySQL

# Ubuntu / Debian
sudo apt update
sudo apt install mysql-server-8.0

# Start and enable
sudo systemctl start mysql
sudo systemctl enable mysql

# Secure the installation
sudo mysql_secure_installation

2. Create the BadgerPanel Admin User

The panel needs a MySQL user with privileges to create databases and users:

-- Connect to MySQL as root
mysql -u root -p

-- Create the admin user for BadgerPanel
CREATE USER 'badgerpanel'@'%' IDENTIFIED BY 'a-strong-random-password';

-- Grant necessary privileges
GRANT CREATE, ALTER, DROP, INSERT, UPDATE, DELETE, SELECT,
      REFERENCES, RELOAD, PROCESS, LOCK TABLES,
      CREATE USER
ON *.* TO 'badgerpanel'@'%' WITH GRANT OPTION;

FLUSH PRIVILEGES;

Host Access

The '%' in the user definition allows connections from any host. For better security, replace % with the panel server's IP address:

CREATE USER 'badgerpanel'@'10.0.0.5' IDENTIFIED BY 'a-strong-random-password';

3. Configure Remote Access

Edit the MySQL configuration to allow remote connections:

sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf

Change the bind address:

# Allow connections from any interface
bind-address = 0.0.0.0

# Or restrict to a specific interface
# bind-address = 10.0.0.10

Restart MySQL:

sudo systemctl restart mysql

4. Firewall Rules

Allow MySQL connections from the panel server and game server nodes:

# Allow from panel server
sudo ufw allow from 10.0.0.5 to any port 3306

# Allow from game server nodes
sudo ufw allow from 10.0.0.0/24 to any port 3306

Public Access

Never expose MySQL port 3306 to the public internet. Only allow connections from trusted IPs (your panel server and game server nodes).

Option B: Using the Panel's MySQL Instance

For smaller deployments, you can use the same MySQL instance that the panel uses. This is simpler but means game server database load shares resources with the panel.

1. Create the Database Admin User

Connect to the panel's MySQL container:

cd /opt/badgerpanel
docker compose exec mysql mysql -u root -p"$DB_ROOT_PASSWORD"

Create a user for managing game server databases:

CREATE USER 'badgerpanel_hosts'@'%' IDENTIFIED BY 'a-strong-random-password';

GRANT CREATE, ALTER, DROP, INSERT, UPDATE, DELETE, SELECT,
      REFERENCES, RELOAD, PROCESS, LOCK TABLES,
      CREATE USER
ON *.* TO 'badgerpanel_hosts'@'%' WITH GRANT OPTION;

FLUSH PRIVILEGES;

2. Note the Connection Details

For the panel's built-in MySQL, the connection details are:

Field	Value
Host	Your panel server's public IP or hostname
Port	3306 (must be exposed in Docker Compose)
Username	badgerpanel_hosts
Password	The password you set

Exposing MySQL Port

By default, the panel's MySQL port is not exposed publicly. You need to add a port mapping in docker-compose.yml or use a docker-compose.override.yml:

services:
  mysql:
    ports:
      - "3306:3306"

Only do this if you also configure firewall rules to restrict access.

Register the Database Host in the Panel

1. Log into the panel as an administrator
2. Navigate to Admin > Databases (or Admin > Database Hosts)
3. Click Create Host
4. Fill in the details:

Field	Description	Example
Name	Display name	US-East MySQL
Host	MySQL server hostname or IP	db.your-domain.com
Port	MySQL server port	3306
Username	Admin user created above	badgerpanel
Password	Admin user password	your-password
Max Databases	Maximum databases on this host (0 = unlimited)	100

5. Click Create -- the panel will test the connection before saving

Multiple Database Hosts

You can register multiple database hosts. This allows you to distribute game server databases across servers, manage capacity, and provide region-specific database servers.

Managing Game Server Databases

Creating a Database

Users create databases from their server dashboard:

1. Navigate to the server in the client area
2. Click the Databases tab
3. Click Create Database
4. The panel provisions the database and displays connection details:
   • Host -- MySQL server address
   • Port -- MySQL server port
   • Database -- Generated database name
   • Username -- Generated username
   • Password -- Generated secure password

Database Limits

The number of databases per server is controlled by the server's resource allocation:

• Set during server creation in the admin panel
• Can be modified in Admin > Servers > [Server] > Build Configuration
• A limit of 0 means no databases allowed

Password Rotation

Users can rotate their database password from the dashboard:

1. Go to the Databases tab on their server
2. Click the Rotate Password button on a database
3. A new secure password is generated and displayed
4. The old password stops working immediately

Plugin Configuration

After rotating a database password, the user must update the password in any game server plugins that use the database. The server may need to be restarted for plugins to reconnect with the new password.

phpMyAdmin Integration

If you have phpMyAdmin set up, BadgerPanel can integrate with it:

MySQL Performance Tuning

For database hosts serving many game servers, consider these MySQL performance settings:

# /etc/mysql/mysql.conf.d/mysqld.cnf

[mysqld]
# InnoDB settings
innodb_buffer_pool_size = 1G          # 50-70% of available RAM
innodb_log_file_size = 256M
innodb_flush_method = O_DIRECT
innodb_flush_log_at_trx_commit = 2    # Slight durability tradeoff for performance

# Connection settings
max_connections = 500                  # Adjust based on number of game servers
wait_timeout = 600
interactive_timeout = 600

# Query cache (disabled in MySQL 8.0+, use ProxySQL if needed)

# Logging
slow_query_log = 1
slow_query_log_file = /var/log/mysql/slow.log
long_query_time = 2

Restart MySQL after changes:

sudo systemctl restart mysql

Backup Considerations

Game server databases should be backed up regularly:

# Back up all game server databases
mysqldump -u root -p --all-databases --single-transaction > /backup/all-databases-$(date +%Y%m%d).sql

# Back up a specific database
mysqldump -u root -p specific_database > /backup/specific-database-$(date +%Y%m%d).sql

Automated Backups

Set up a cron job for daily database backups:

# Add to crontab
0 3 * * * mysqldump -u root -p'password' --all-databases --single-transaction | gzip > /backup/databases-$(date +\%Y\%m\%d).sql.gz

Troubleshooting

"Access denied" When Creating Database Host

• Verify the MySQL user has WITH GRANT OPTION
• Check the user can connect from the panel's IP
• Test the connection manually: mysql -u badgerpanel -p -h db.your-domain.com

Game Servers Can't Connect to Database

• Verify the MySQL server allows connections from game server node IPs
• Check firewall rules on the MySQL server
• Ensure the bind-address is not set to 127.0.0.1
• Test from the game server node: mysql -u generated_user -p -h db.your-domain.com generated_database

Too Many Connections

• Increase max_connections in MySQL configuration
• Check for connection leaks in game server plugins
• Monitor active connections: SHOW PROCESSLIST;

Next Steps

• Getting Started -- Panel deployment guide
• Configuration -- Panel configuration reference
• Billing Setup -- Set up billing and products