Self Hosting
Welcome to the GAwesomeBot Community self-hosting guide™! If you're just here for the bot, and don't really like all the tech talk, just visit the official GAwesomeBot page and click 'Add' to invite GAwesomeBot to your server.
For all the people who are interested in setting up GAwesomeBot, and don't mind getting their hands dirty in CLI's, environments, configuration, non-SQL Databases and a buttload of exceptions; come along! If you did not understand any of what I just said, I recommend you reconsider line 2 of this article. But seriously. It is important that you question yourself in terms of experience with hosting node.js applications that rely on more than just a "node bot.js". If you don't understand anything happening in this guide, it is most likely your fault rather than ours. Drop a message in the #self-hosting discord channel if you're having trouble, but don't always expect to be helped. Right, let's get started;
- Knowledge about node.js, mongodb, a shell like bash, the OS you're hosting GAB on and some more general sysadmin knowledge can't hurt.
- Acceptance of the fact that we are not always able to help you in the discord server. Ask questions? Go ahead. Ping specific people/roles multiple times? Big no no.
- A server of sorts if you want your bot to be online 24/7 and accessible for the public. You can use a local machine for hosting, but you would need to forward ports to allow others to connect to your bot's web interface, and keep the machine on all night if you want the bot to be online 24/7. Don't have money for all those crazy server thingies? Check out our heroku self-hosting guide.
- If you don't want to share your IP address, you will need a domain (preferably proxied by a service like Cloudflare).
- A setup instance of node.js v6 or newer.
First of all, we need to setup a discord application and tie a bot account to that application. Go to the Discord applications page and create a New App. Then fill out the App name and description fields and upload a nice looking bot avatar if wanted. After that, click on "Add Redirect" underneath "Redirect URI(s)" and enter "http://YOURDOMAIN.ORIP:PORT/login/callback". Example: "http://example.com:8080/login/callback" or "http://0.0.0.0:8008/login/callback". Then click Create App. After the application has been created, click "Create a Bot User". Then take note of your Client ID, Client Secret, and bot Token.
NB: If you plan to run your bot with SSL (see below), don't forget to add an additional redirect URL: "https://YOURDOMAIN.ORIP:HTTPSPORT/login/callback" (you can add more than one).
Now, it's time to decide what branch you want to be running. We've got plenty of options!
- Master: For all those of you who want to be snug and comfortable with your safe and stable GAB instance.
- Experimental: If you want to catch new features and enhancements before all the stable losers, choose this branch! Be aware that these new features and enhancements may contain more bugs than the stable branch.
- Development: This branch should not be used for production! But only if you want to help us out developing GAB!
- Indev-4.0.2: This is the current updated branch, which will soon™ become v5.0; The others should be avoided as they are buggy, and outdated..
First, create a folder in which you want to host AB, go into that dir, and run
git clone -b master https://github.com/GilbertGobbels/GAwesomeBot . for the stable branch.
You should now have GAB's files in the dir you're currently in. For the rest of the guide, we're gonna assume you stay in this dir unless told otherwise.
If you wish to download the experimental branch, you should run the following instead git clone -b experimental https://github.com/GilbertGobbels/GAwesomeBot . and for development, just swap out experimental with development, and for indev use indev-4.0.2. Easy peasy!
NB: If you are on the development branch, GAB's updating system will be disabled. If you want to catch the newest files, you're going to have to use git.
Open Configuration/config.json and fill in the following values as shown:
- platform: Leave as "discord"
- shard_count: The amount of shards the bot should be using when connecting to discord. I'd say around 4 is fine but it heavily depends on the amount of servers your bot is supposed to join. You should calculate shards based off no. of servers / 1000, or one shard per thousand servers.
- hosting_url: The URL your web interface will be accessible from. This value is automatically used when GAwesomeBot needs to lead users to the web interface and in internal links on the web interface. So make sure you double-check you can just copy-paste the value into your browser without problems! Don't forget the trailing slash (
/- i.e.http(s)://YOURDOMAIN.ORIP:PORT/instead ofhttp(s)://YOURDOMAIN.ORIP:PORT). - http_port: The port your web interface should be listening on for http connections. If you use cloudflare to proxy your domain (which you should) you must choose a port that Cloudflare can access. 8080 will work, but if that's already in use please see this article which lists all ports that will work with cloudflare. Remember that any ports underneath 1024 require the use of authbind or sudo. development branch only, on master branch named server_port
- https_port: The port your web interface should be listening on for https connections. Requires cert and privKey values to be filled in to work. development branch only
- cert: The file path to your domain's full cert chain. If you don't have one, leave it empty (You won't be able to use https). development branch only
- privKey: The file path to your domain's private key. If you don't have one, leave it empty (You won't be able to use https). development branch only
- httpsRedirect: If incoming http connections should be redirected to https. development branch only
- server_ip: The IP you want your web interface to listen on. Recommended: 0.0.0.0 to listen to all possible addresses your machine is bound to.
- db_url: The URL pointing at the mongodb instance you're setting up. More on this later. Recommended: leave it as it is.
- maintainers: An array containing the Discord User IDs of your bot maintainers. Maintainers are like global bot admins. Besides, they can control the maintainer console which includes options to (among others) set Wiki Maintainers, edit the bot's profile (name/avatar/playing message), set more maintainers/remove others and manage servers (force the bot to leave servers, send a message to a server, etc.). They can also create wiki articles and blog posts. Bot Maintainers have great power over your bot and control the admin panel of all servers your bot has joined. It is VERY important to keep your maintainer list as small as possible to avoid abuse of power. When finding a self-hosted bot, make sure this is the case on the instance in question. Example:
["108892284119977984"] - header_image: set this to header-bg.jpg
- pm_forward: Set this to true if you want GAwesomeBot to PM all maintainers all PM's that he receives. Set this to false if you don't want this.
- version: You should NOT modify this value. Doing so will disable your updater.
- branch: This value should ONLY be modified if you are running a development instance.
- oauth_link: https://discordapp.com/oauth2/authorize?&client\_id=YOUR\_CLIENT\_ID&scope=bot&permissions=470019135
- discord_link: The link to whatever discord server you want the discord buttons on your web interface to point to.
- donate_charities: The charities you want the donate button to point to. This value should be an array of JSON objects in this template:
{ donate_url: "http://example.com/link/to/charity/donation", icon_url: "http://example.com/link/to/charity/icon", name: "The charity's name", country: "If set, the charity's country code. E.g. UK or NL" }
Any other values that are not noted here are currently not working or do not require any editing. Save and close config.json, and open Configuration/auth.json. Then fill in the values like this:
- platform.client_id: Enter the client id you noted earlier on your discord application's config page.
- platform.client_secret: Enter the client secret you noted earlier on your discord application's config page.
- platform.login_token: Enter the bot Token you noted earlier on your discord application's config page.
- tokens.giphy_api_key: Fill out this form to get your own giphy api key or use the public API key "dc6zaTOxFJmzC"
- tokens.google_api_key: Go to the Google Developer Console and click on "Project" in the top-left. Then select "Create new project". Give your project a recognizable name for you, and create the project. Then, hit "login details" and create new login details. Choose to create an API-key. Copy the API key that popped up and enter it in auth.json.
- tokens.google_cse_key: Go to here to create a new custom search engine and fill out the form (under the 'sites to search' you can simply put in
*.google.com). After creating the CSE, go to its config and click "Search engine-ID". Then copy that ID and paste it in auth.json - From the Google Developer Console, ensure your newly created project is selected in the top left, and then click "Library" in the left hand side menu (below "Dashboard, and above "Credentials"). Under the heading entitled "YouTube APIs", click on "YouTube Data API" and select "Enable". Go back to 'Library' and select "URL Shortener API" under the heading "Other popular APIs", and select to enable the URL Shortener API.
- tokens.imgur_api_key Hop unto this link and fill out the form to create a new API client. You can fill in whatever in all values, apart from Authorization type. You should select "Anonymous usage without user authorization" there. After creating select the imgur client ID that appears and fill it into auth.json
- tokens.microsoft_client_id: Follow this guide to get your Client ID and Client Secret and place both of them into auth.json in the right fields
- tokens.microsoft_client_secret: See above
- tokens.twitch_client_id: Take a look at twitch's annoucnement on Client ID's which contains a small guide on how to get an application registered and get its client ID. For redirect URI, the hosting_url will do. Place the client id acquired by creating the application into auth.json
- tokens.wolfram_app_id: Sign up for wolfram if you haven't already. Then create an application and copy its app ID once created. Then paste it into auth.json. Close and save auth.json. If you don't want to use a certain feature (such as wolfram) you can leave its value as an empty string. However note that this command will not function while being advertised as working in further bot documentation and bot help.
Finally, if there is no Extensions directory in your GAwesomeBot directory, please create one (there is no need to put any files in there, but the empty directory must exist otherwise extensions will not save).
MongoDB is a non-SQL database that GAB uses to store all its server- and userdata in. Because installing it is different on most OS's, it's best if you follow their offical guide on installing the community-edition. Make sure you install the latest MongoDB version that's available on their website! If you've changed the port in config.db_url you need to set mongodb to whatever port you've set GAB to connect to. If you haven't touched anything, it's all fine.
We're almost there! Now you just need to open a console/terminal, enter the GAB root dir, and run npm install. Once that's finished run GAB with node bot.js. Boom! You're done. However, there are a few more tips and tricks with hosting GAB that I feel the need to mention;
We all know some links in the GAB Web Interface are broken. And while fixes are on the way, it's best to create a wiki article simply called "Home" to hotfix most problems.
Talking about the wiki, writing one on your own is hard and time consuming. That's why you can set additional wiki contributors in the maintainer's console. These wiki contributors will be able to edit, delete, and create any wiki articles. While you're at it, why not set some bot maintainers? Apart from wiki managing, bot maintainers can also create blog posts for all your users to read (or ignore). Do note however that Bot Maintainers have a lot of power, and the position should not be taken lightly.
To make sure your bot restarts when exceptions are thrown (which will happen a lot) it is recommended to use pm2 to manage and keep your node processes alive, including GAB!
Follow their guide on how to quickly setup pm2 for production. Then, you can start GAB with pm2 start bot.js --name GAwesomeBot. After this, you can;
- Stop GAB using
pm2 stop GAwesomeBot - Restart GAB using
pm2 restart GAwesomeBot - See GAB's logs using
pm2 logs GAwesomeBot - Quickly see how GAB's doing using
pm2 status GAwesomeBot
... All without having to be in GAB's root dir. You can also setup keymetrics to monitor GAB, but that's a story for another time.
There's a lot in there to play around with, have fun! (Warning: side effects of playing around with dangerous maintainer settings may include but are not limited to; permanent loss of hearing, spontaneous combustion of hosting machine, and a spooky curse)
Alright, I think that's it. I hope you've managed to setup your own instance of GAB... Please do still use mine though.
If you have any problems, or feel the need to point out I'm an idiot and missed something, do so in the community discord (without mentioning me pls)
Have fun self-hosting, AwesomeUsers!
BitQuote was here ( ͡° ͜ʖ ͡°)