Over my time in TPH, I have noticed that a common woe aspiring bot developers have is that they are unable to host their Discord bot online as they may not have access to a credit card.

Introducing Heroku!

While the official Discord bots used in TPH - like HotBot - is hosted via paid platforms, there are free alternatives to deploying your bot online. This is where Heroku comes into the picture!

Heroku is a cloud platform that lets companies build, deliver, monitor and scale apps — we’re the fastest way to go from idea to URL, bypassing all those infrastructure headaches.

Heroku’s free tier does not require any credit card information and has sufficient uptime for your basic bot development needs and it is a great starting place to understand hosting.

How does Heroku work?

Before diving into setting up a Discord bot on Heroku, it is best to explain how Heroku is used. Heroku relies on the Git version control system (VCS) to manage an application. This means that it integrates well with any existing projects that already use Git. Do not fret, even if your application does not use Git, the configuration and setup for Heroku is still simple.

By using Git, Heroku receives the project files directly and it is responsible for building the project. This is unlike other hosting platforms where you would often only supply the final executable - a .jar file in our case - to the hosting platform to run.

In order for Heroku to understand how it will build and deploy your application, you must provide a Procfile.

The Procfile is comprised of two key components - the dyno to run the application on and the commands to run your application.

According to the Heroku documentation on dynos, dynos are containers that are used to run and scale all Heroku applications. Rather than worrying about configuring your build environment or OS, you can focus on building your applications and allowing Heroku to take over the build and deployment process. For all Discord bots, we will use a worker dyno.

The build commands we supply correspond to the build commands we use to run our bots locally.

As Heroku uses the project files to determine the type of tools we are using, we do not need to specify the instructions to create the executable. In our case, since we are using Maven, it can intelligently detect the pom.xml file and create the .jar accordingly. This leaves us with only the run commands to include in our Procfile .

Finally, to tighten security, we will store all bot tokens in Heroku’s config vars. From a code perspective, these config vars are simply environment variables available to our applications. This allows us to load our bot token during runtime and prevent the bot token from being leaked.

Thus, we can define our deployment plan as such:

  1. Initialise the codebase as a Git repository
  2. Create a Heroku application for the bot
  3. Create a Procfile to supply instructions for Heroku to run the bot
  4. Store the bot token as a config var to be used by your bot

What I have just presented is a general overview of Heroku as a hosting platform. I will be diving into the implementation in the following sections.

Getting started

For this article, I will be using a very simple Discord bot written in Kotlin. I have chosen to use JDA as the focus of this guide is to understand Heroku. The code repository can be found here.

If you wish to follow along, you can get the repository via

1
2

$ git clone https://github.com/woojiahao/discord-heroku-deployment-demo ping-bot
$ cd ping-bot/

Aside from that, basic understanding of the following is good to have to understand the technical details of this guide.

  1. Git - version control system that integrates with Heroku to enable easy deployments
  2. Maven - build tool for Kotlin to manage application dependencies

In Kotlin/Java, we are looking to create a .jar file. This .jar file can be thought of like a .exe file. Essentially, it bundles the application and allows us to run our bot without having to fire up an IDE.

To create this .jar file, we will use Maven. For more information about using Maven to create .jar files, refer to this guide.

With the formalities out of the way, let’s get down to deploying our bot.

Installing Heroku

You will have to install Heroku onto your machine to execute the following commands in the command line. You can find the installation instructions for Heroku here.

To ensure that you have installed Heroku successfully, run heroku --version. My version of Heroku is heroku/7.39.2 linux-x64 node-v13.12.0

Setup a Git repository

As mentioned earlier, we need to ensure that our application is a Git repository for Heroku to work.

While it is recommended to publish your repository to GitHub ( or any other version control website), it is not necessary for deploying your applicaiton to Heroku.

If you are using the sample bot, it is already a Git repository.

If you are deploying your own bot, initialise a repository by using the following command inside the root folder of your codebase.

1

$ git init

Create a new Heroku application

Then, we want to create a Heroku application.

1

$ heroku create [project name]

The project name is optional and will be automatically generated if not provided. It is recommended that you give a name to be organised.

To ensure that the Heroku application has been created, run the git remote -v command to list the remotes of your repository. Should your application have been created successfully, you will see a new remote added linking to a Heroku Git remote.

Results of git remote -v

With the Heroku application created, we can begin configuring our repository to deploy to Heroku.

Creating a Procfile

As explained earlier, the Procfile acts as a build instruction manual for our application. It instructs Heroku how we want to run our application. Heroku takes over the rest and helps with managing our build environment.

For my sample bot, the Procfile looks like this:

worker: java -jar target/Bot.jar

Let’s breakdown this file. We first declare the dyno type as worker. Then, we specify the command to run our .jar file.

Heroku is able to intelligently detect that our Kotlin application uses Maven as a build tool and runs the mvn clean install command to create our Bot.jar file. Then, it will use the commands in the Procfile to run the application.

Securing Discord bot tokens

A Discord bot requires a token to run.

You can obtain this bot token when you make a new Discord bot from the Discord developer dashboard. However, you do not want to expose this token in your repository as this would mean that others could launch and access your bot.

As mentioned earlier, we will make use of Heroku’s config vars to safely store and access this token.

We will add our bot’s token as an environment variable and use System.getenv() method to retrieve this value.

1

$ heroku config:set BOT_TOKEN=<bot token>

Inside the Bot.kt file, you will find the following lines in the main() function.

1
2

val token = System.getenv("BOT_TOKEN")
  ?: throw Exception("Must include bot token in environment variable for bot to run")

This will retrieve the corresponding environment variable that we have stored in Heroku. If there is no environment variable present, we will stop the bot from launching and display an error.

An additional benefit of storing our bot tokens as an environment variable is that we are able to store the bot token locally as an environment variable which streamlines our development process as we could have a separate token used for a development/testing bot.

Launching the bot

After configuring everything, commit all the changes to your project, and push it to the heroku remote.

1
2
3

$ git add .
$ git commit -am "Setup Heroku"
$ git push heroku master

If you encounter a problem with pushing to the heroku remote, use the command heroku logs --tail and find the latest error messages to debug any errors.

After pushing the changes, Heroku will build your application. However, it is not online yet as you have to scale your application. This tells Heroku how many instances of your application you wish to run. For our case, we can go with one worker dyno.

1

$ heroku ps:scale worker=1

You can now invite your bot to a server and test it out. If you’re using the sample PingBot, you can use !ping and expect the bot to respond with Pong!.

Now what?

Congratulations! You have just deployed a Discord bot onto Heroku! When you make changes to the bot, you are free to commit and push those changes to the heroku remote to update the bot that is online.

Here are some tips for developing with Heroku.

  1. While working on your development copy of the bot, it is recommended that you obtain a seprate bot token and attach it as an environment variable to your local development environment. Doing so allows you to maintain your bot’s uptime while making changes.
  2. If you encounter any errors or your bot is not responding, use the heroku logs --tail command to view the logs of your application. Doing so allows you to check if there were any errors while running your project.
  3. If you require persistent storage, Heroku comes with a free tier plugin for PostgreSQL. Heroku - by default - has ephemeral storage, meaning it does not maintain new files after each build.

Conclusion

Heroku offers a free alternative to many hosting platforms and is a perfect platform for aspiring bot developers to begin.

More resources on hosting JVM-based applications on Heroku: