Self Hosting
This wiki page will guide you through setting up your own instance of AwesomeBot, from start to finish!
But you might be wondering whether it's a good idea to make your own AwesomeBot. There's a perfectly good official AwesomeBot available for use, but we've open sourced the bot for people who want to modify him beyond extensions. Perhaps you want to change his name, icon, or implement powerful, application-specific commands.
Important: We provide no support for anything self-host related in our official Discord server. We did not create the bot with the intention of letting other people self-host it. It is open-source so that you can if you want, but you are on your own. Even if the issue is code related, you are still on your own to resolve it.
- Make sure you have Git and NodeJS v5.11 or 5.12 installed on your computer.
- For all the latest features, use
git clone https://github.com/BitQuote/AwesomeBot.git. If you want a very stable bot, grab the latest milestone release. - Extract the archive if necessary
- Run
npm installin the bot's directory to fetch the required Node modules
AwesomeBot recently migrated to the official Discord API, which requires bots to operate from a special bot account that has certain restrictions and advantages compared to a normal use account. If you run a bot from a normal account, it will be suspended, so...don't do that.
So let's get started: head over to the My Applications page in the Discord Developers section and click "New Application". You'll be taken to a page that looks like this:
The bot name can be anything you wish, other than "AwesomeBot" or anything similar that might cause confusion between your instance and the official version. The redirect URI should ideally be the endpoint for wherever you're hosting the bot or the link to your fork of this repo on GitHub. You may choose an app icon or write a description, but these will not be carried over into your bot. Once you're done, you'll be taken to the info page for your new bot application, which looks something like this:
Open auth.json in the bot directory and fill in the values for token and client_id with the credentials for your Discord bot application. Make sure to include the existing quotation marks. You can include the URL for the bot's avatar if you want, but this can be changed at any time via the maintainer console.
Important to note: Recent API changes require you to prefix your 'token' with "Bot " (make sure to keep that blank space between "Bot" and your actual token).
Now that we have the bot account ready, we can get all our API keys...
Just one thing: we know carbon_key is listed in auth.json. Don't worry about this and don't use it.
To get data from around the web, AwesomeBot needs access to quite a few APIs, as you see in auth.json. Let's walk through getting the necessary credentials for each of them:
This is necessary for image and YouTube search. Sign into your Google account and go to the developer console. Click "create project" and use the same name as your Discord bot application. Make sure to add the "custom search", "YouTube data", and "URL shortener" APIs to the project. Finally, go to the Credentials section and create an API key. Paste this value into auth.json.
In order to search images, you'll need to create a Google Custom Search Engine (CSE) that's restricted to images. The configuration for it should look like this:
Paste the search engine ID into auth.json.
Giphy is the provider of memes GIFs in AwesomeBot. Click here and sign up for an API key. Use the same application name as your Discord bot app and select "search API"; you'll receive the key within minutes. Paste it into auth.json.
For the imgur command to work, you'll need to register an OAuth application. Select "anonymous usage without user authentication" and paste the client ID you receive into auth.json.
Wolfram|Alpha is a powerful resource and one of the most informative commands in AwesomeBot. First, sign up for a Wolfram Developer Account. This requires some personal information, but it is never exposed to users of your bot. Once you're logged in, click "get an AppID" and use the same application name as your Discord bot app. Paste the ID into auth.json.
AwesomeBot gets currency conversions from Open Exchange Rates. Sign up for the Forever Free API plan and paste your APP ID into auth.json.
The translate command uses Microsoft's text translation API, but you must first create an application on MSDN. Register a new one here, set a client ID, and paste it into auth.json. Also paste the auto-generated client secret.
Once you're done with that, head over to the MDN Marketplace and subscribe to the Microsoft Translator API. You should probably choose the first option, which is free and does not require a credit card.
Now that auth.json is complete, there's just one more thing you need to setup. Find your personal Discord user ID by joining our private server and using !profile. Paste this into the maintainer section in data/config.json.
Important: Don't forget to add the URL that points to the web panel of your bot (IP/Domain:Port) into the hosting section inside data/config.json.
Finally, you can start the bot by running node bot.js in the bot directory!
You'll notice that the bot, while up and running, is basically useless at this point. To really start using it, you have to add it to a server. To do that, find your bot's OAuth URL. It will look something like this:
https://discord.com/oauth2/authorize?&client_id=YOUR_BOTS_CLIENT_ID&scope=bot&permissions=0
Make sure to replace YOUR_BOTS_CLIENT_ID with the Client ID found on your Discord bot app's info page. Go to the URL in a web browser, and you'll be able to add your bot to a server (you must have the "Manage Server" permission):
Click "Authorize" and you're ready to go! Learn more about configuring the bot »
An important component of AwesomeBot is the web interface, where you can view the bot's status and configure him in general or in servers. If you're running the bot locally, the web interface is accessible at localhost:8080. However, running the bot locally is often impractical and unreliable (since your computer might not always be on).
We recommend hosting your bot on a cloud application hosting service. There are many available, ranging in price, including Amazon AWS, Google Cloud Platform, Heroku, Microsoft Azure, and more. While these offer a robust feature set and high performance, they're often expensive and unnecessary simply for hosting a Discord bot. Instead, we suggest RedHat's OpenShift service, which allows up to 3 applications for free with good uptime and reliable performance.
Please note: OpenShift has now changed to a 30 day trial, we recommend looking for a provider on https://lowendbox.com/ to suit the small amount of resources the bot needs.
This article provides an easy-to-follow guide to hosting a NodeJS app (AwesomeBot is built with NodeJS) on OpenShift. Also, make sure to use this OpenShift cartridge for an up-to-date NodeJS.
Regardless of which hosting provider you choose, make sure to put the URL that points to the bot's web interface in the hosting section of config.json.