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.
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.
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 is comprised of two key components - the dyno to run the application on and the commands to run your
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
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:
Procfileto supply instructions for Heroku to run the 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.
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
$ 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.
manage application dependencies
In Kotlin/Java, we are looking to create a
.jar file. This
.jar file can be thought of like a
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
With the formalities out of the way, let's get down to deploying our bot.
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
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.
$ git init
Then, we want to create a Heroku application.
$ 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
With the Heroku application created, we can begin configuring our repository to deploy to Heroku.
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
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
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.
$ heroku config:set BOT_TOKEN=<bot token>
Bot.kt file, you will find the following lines in the
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.
After configuring everything, commit all the changes to your project, and push it to the
$ 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.
$ 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
expect the bot to respond with
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.
heroku logs --tailcommand to view the logs of your application. Doing so allows you to check if there were any errors while running your project.
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: