Skip to content

Self hosting guide

Jump to bottom
Alex1304 edited this page Apr 16, 2019 · 9 revisions

This document will show you how to host your own instance of UltimateGDBot step by step.

Prerequisites

Java Development Kit 11

UltimateGDBot has been developed in Java 11, which is a very recent version of Java released in September 2018. Since Java 8 is currently still the most used version, it is likely that you need to perform the upgrade. I am not going to make a tutorial on how to install Java 11 on your system as you can find that easily on Google, but in the end you should be getting a similar output when doing java -version in a terminal:

openjdk version "11" 2018-09-25
OpenJDK Runtime Environment 18.9 (build 11+28)
OpenJDK 64-Bit Server VM 18.9 (build 11+28, mixed mode)

If you see version 11, you're good to go.

MySQL server

Also, you will need a MySQL server. You shouldn't need tools like phpmyadmin because the bot will automatically create the necessary tables for you. Just make sure that the server is running and that you can connect to it with a login/password fine.

Prepare the project

Go to the Releases page of this repository and download the ultimategdbot.zip file attached to the latest patch notes. Unzip the contents in the directory of your choice. The archive contains the following:

  • The JAR ultimategdbot.jar that contains the compiled code of the bot.
  • A config/ directory, empty, where we will put the bot configuration files
  • A config-example/ directory that contains templates for configuration files
  • A plugins/ directory that is empty by default, but here you can put extensions to add more features to the bot.

In fact, ultimategdbot.jar does not include any Geometry Dash command. It only contains the implementation of some basic commands such as help or ping. In order to add Geometry Dash features, you need to download the plugin at the Releases page of the UltimateGDBot GD Plugin repository. The file to download is ultimategdbot-gd-plugin.jar in the latest patch notes. Once you have downloaded the file, copy it and paste it into the plugins/ directory.

Configure the bot

Upload custom emojis

If you are using the Geometry Dash plugin, you will need custom emojis that the bot will use in its messages / embeds. Download the emoji set here, and upload all emojis to different servers of your choice. Make sure that the bot is present in the servers you upload the emojis in, otherwise the bot won't be able to use them.

Create a new database in your MySQL server

If you don't have a database created already, login to your MySQL server and execute the following statement to create a new database for UltimateGDBot:

CREATE DATABASE ultimategdbot;

Edit the configuration files

Configuration files are located in the config/ subfolder. By default, this folder is empty, because configuration files aren't be tracked by Git due to them containing sensitive information, such as the bot token or the database credentials. However you can find templates for these configuration files in the config-example/ subfolder. So the first thing you need to do is to copy all contents from config-example/ to config/.

There are 3 important configuration files:

  • bot.properties: configures the bot itself (token, emoji guilds, debug log channel IDs, etc)
  • hibernate.properties: configures the database
  • plugins.properties: configures the plugins

First, open bot.properties with a text editor, and fill in all fields by following instructions given in the file comments. When it asks you to copy IDs, make sure you have Developer mode enabled in Discord to be able to copy them.

Then, open hibernate.properties. This is where you will give the database credentials to allow the bot to connect to it. In hibernate.hikari.dataSource.url, you can specifying the host, the port and the database name. The syntax is the following: jdbc:mysql://<hostname>[:<port>] /<database_name> For example, if your host is localhost, the port is the default one and you database is named ultimategdbot, the url would be jdbc:mysql://localhost/ultimategdbot. Your username and password need to be specified in respectively hibernate.hikari.dataSource.user and hibernate.hikari.dataSource.password fields. Optionally, you can disable the printing of SQL queries made by the bot in logs by switching hibernate.show_sql to false. This might be useful for debugging and performance monitoring purposes, but it might not interest you.

Finally, open plugins.properties. The file is empty by default, which is normal because the bot comes with no plugins by default. Each plugin should provide in their documentation which fields can be added to this file in order to configure them. Since a such documentation is not yet available for the Geometry Dash plugin, just follow the instructions below:

  1. Add a field named gdplugin.username and input the username of your bot account in Geometry Dash
  2. Add a field named gdplugin.password and input the password of your bot account in Geometry Dash
  3. If you are hosting UltimateGDBot for a GDPS, add a field named gdplugin.host and input the host URL of your GDPS, without the protocol (http://) and without a trailing slash.

Create the contents of the about command

UltimateGDBot's about command displays info on the bot itself, such as its version, its description, the number of servers it's in, etc. You are able to customize the contents of the command by editing file called about.txt in config/. Please note that the content of the file must not exceed 2000 characters, otherwise the about command will fail due to Discord's character limit. In order to display dynamic content in the command, you can use some variables anywhere in the file. Those variables will be substituted with the corresponding value at runtime:

  • {{ bot_name }} The name of the bot, as you named it in the Applications page of the Discord Developer portal
  • {{ project_version }} The version number you provided in bot.properties
  • {{ bot_owner }} The Discord tag of the application owner
  • {{ server_count }} The number of servers the bot is in
  • {{ user_count }} The number of users that the bot knows across all servers
  • {{ bot_auth_link }} The link to add the bot to servers, as specified in bot.properties
  • {{ support_server_invite_link }} The discord.gg link to the support server, as specified in bot.properties.

Run the bot!

You are now ready to launch the bot! Here is the command line to proceed:

java -cp ultimategdbot.jar:config:plugins/* com.github.alex1304.ultimategdbot.core.Main

Note: the above command works on Linux and MacOS. If you are on Windows, you need to replace : with ; in the classpath declaration. The command for Windows would be:

java -cp ultimategdbot.jar;config;plugins/* com.github.alex1304.ultimategdbot.core.Main

On the first boot, the bot will automatically create the necessary tables in the database you specified. The bot will log everything in the standard output as well as in a log file located in a newly created logs/ folder.

If you need assistance with self-hosting, please DM Alex1304#9704 on Discord.

Clone this wiki locally