-
Notifications
You must be signed in to change notification settings - Fork 5
hosting_locutus
This guide will walk you through the process of self hosting the Locutus bot. Follow the steps below to obtain the Locutus .jar
file, run the bot, configure the config.yaml
file, and set up the credentials for Google Sheets.
-
Obtaining a Locutus
.jar
file - Running the jar file
- Setting up the config yaml
- Credentials for Google Sheets
If you prefer to skip the compilation process, you can download a precompiled Locutus .jar
file from the following location:
-
Locutus Precompiled Jar (look for the file named
shadowJar-Locutus-1.0-SNAPSHOT.jar
) - Example update script (windows)
If you want to build the Locutus bot from the source code, follow these steps:
- The Locutus source code is hosted on GitHub at xdnw/locutus.
- On the GitHub page, you can select the branch you want to access. The main branch is called
master
, but there may be development branches with additional features.Note: Development branches may not compile or run.
Selecting a branch:
-
(option 1) Downloading the code as a zip: Extract the code from the zip file into the directory you want
-
(option 2) Clone the repository with git. Install git: https://git-scm.com/downloads Use the provided clone url from command line.
-
After downloading the source code, navigate to the directory that contains all the Locutus source files.
-
Open a command prompt or terminal in that directory. (see: https://www.lifewire.com/open-command-prompt-in-a-folder-5185505)
- Example for Windows:
-
Run the following command:
./gradlew build shadowJar
. -
After the compilation finishes, you can find the compiled
.jar
file in thelocutus/build/libs
folder. Copy theshadowJar-Locutus-1.0-SNAPSHOT.jar
to the directory you want to host Locutus in. (The build folder may be deleted when compiling a new jar)
To run the Locutus .jar
file, you need to have Java installed on your system. Follow these steps:
- Download and install Java. You will need Java 22 or a newer version. You can download Java from Oracle. I use Oracle's GraalVM for its scripting and profiling support GraalVM Download.
- Note: If you encounter an
UnsupportedClassVersionError
, it means you are using an outdated Java version. Install Java 22 or newer and ensure it is set as the default version on your system. You can refer to this guide on how to set the default Java version in Windows.
- Note: If you encounter an
- Open a command prompt or terminal.
- Navigate to the directory where you downloaded the Locutus
.jar
file. - Copy the jar to the directory where you want to host the bot from.
Note: Building the jar again may delete the build folder
- Run the following command:
java -jar shadowJar-Locutus-1.0-SNAPSHOT.jar
.- This command executes the Locutus bot. If it's your first run, the application will generate a
config/config.yaml
file and then exit. You will need to configure this file before running the bot again.
- This command executes the Locutus bot. If it's your first run, the application will generate a
The Locutus bot requires a configuration file (config.yaml
) to be set up with your P&W (Politics & War) and Discord details. Follow these steps to set up the config.yaml
file:
- Close the Locutus bot program if it's running.
- Open the
config/config.yaml
file in a text editor. - Provide your P&W and Discord details in the
config.yaml
file.- To register a bot with Discord, go to the Discord Developer Portal and create a new application. Make sure to enable the guild and message intents for your bot user.
- To obtain server IDs, you can refer to this guide on how to find your User, Server, and Message ID.
- To create an invite for your bot go to My Apps page under the "Applications" section, click on your bot application, and open the OAuth2 page.
- In the sidebar, you'll find the OAuth2 URL generator. Select the bot and applications.
- Select the permissions you want to invite the bot with, such as
Administrator
, then copy the URL and paste it into your browser.
- Save the
config.yaml
file after updating it with your details. - Restart the Locutus bot by running the same command as before:
java -jar shadowJar-Locutus-1.0-SNAPSHOT.jar
.
If the Locutus bot fails to load, check the error message. You may need to configure missing values in the config.yaml
file.
If you want to enable credentials for Google Sheets, follow these steps:
- Create credentials for Google Sheets by following the guide on the Google Workspace Developer's Guide: Create credentials.
- During the credential creation process, select
desktop application
to authorize the credentials using a web browser.
- During the credential creation process, select
- Save the credentials as
credentials-sheets.json
andcredentials-drive.json
in theconfig
folder (the same folder as theconfig.yaml
file).- The
credentials-sheets.json
file should contain the authorization details for Google Sheets, and thecredentials-drive.json
file should contain the authorization details for Google Drive. - You can refer to this Stack Overflow answer for an example of how to save your credentials: Example on how to save your credentials.
- Example format for
credentials-sheets.json
:{ "installed": { "client_id": "1053560905219-g86h1oodreg31gh1mfgv0mcdbejq7qmg.apps.googleusercontent.com", "project_id": "quickstart-1579567009568", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://oauth2.googleapis.com/token", "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "client_secret": "XXXX", "redirect_uris": [ "urn:ietf:wg:oauth:2.0:oob", "http://localhost" ] } }
- Example format for
credentials-drive.json
:{ "installed": { "client_id": "1053560905219-s1vbn6vdcmumih44jalu5rps01k769e9.apps.googleusercontent.com", "project_id": "quickstart-1579567009568", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://oauth2.googleapis.com/token", "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "client_secret": "XXXX", "redirect_uris": [ "urn:ietf:wg:oauth:2.0:oob", "http://localhost" ] } }
- The
Use one of the sheet commands to test your credentials.
Congratulations! You have successfully set up the Locutus bot and configured the necessary files. The bot should now be running and ready to use with your Discord server and Google Sheets integration.