Overview

Why IgKnite?

IgKnite, unlike most other Discord bots, is open-source, meaning that all of the aspects of it is open to and maintained by, (yes you guessed it) the community!

IgKnite is also built on top off Discord's bleeding-edge API changes including slash commands, resulting in an interaction method that doesn't include text commands at all. This also means that you will never have the hassle to type in a prefix and then making sure that your command is written perfectly. IgKnite also contains interaction methods like message / user commands which, for most of the time, do not even require you to type anything!

Why this guide?

While the README.md file might not be enough to guide you through the setup phase and the different use cases of IgKnite, this documentation can help you in the initial run. It contains all the necessary information to:

• Add IgKnite to your Discord server
• Self-host the project on your own machine
• Learn about how things are operated under the hood

We hope that you will have a lot of fun using IgKnite and that's why we'll leave the post-documentation stuff to you. After all, exploration is a lot more enjoyable than reading.

Setup

This documentation chapter describes how to add IgKnite to your Discord server using two different authentication methods. It also explains how permissions are handled to later lock specific commands within IgKnite so that you can fully utilize the project's power!

Adding to your Discord Server

The very first, and the very basic, step of using IgKnite is to add it to your precious Discord servers. Traditionally, most of the Discord bots that we see today are hosted already by their corresponding maintainers, and IgKnite is no exception too.

Method 1: The Link

This method has been on Discord for a while now, and involves OAuth URLs.

• If you head over to IgKnite's official website, you will see a button labelled 'Inject' (that is what we call it here; fancy, right?) Simply click it and you will be redirected to one of Discord's child websites which will allow you to add IgKnite to your Discord server.

• Or, you can just click here without going to the website to do the same.
  

Method 2: The Profile

This method, unlike the previous one, is new and uses Discord's In-App Authorization feature.

1. If you have a friend who has IgKnite 'injected' in their Discord server, then you can head over to that server and click on IgKnite's avatar to toggle its profile view.

2. See a large blue button saying 'Add to Server'? Click it and you will be prompted to choose which server you would like to have IgKnite. Note that you might also be asked for an authentication code if you have two-factor authentication enabled in your Discord account.

3. Click on 'Continue'. At this stage, you will see a bunch of ticked options. These represent the global permissions which allow IgKnite to run properly (don't untick any of them, otherwise you might see errors popping in once you start using the bot).

4. Finally, fill in the CAPTCHA requirements to add IgKnite to your Discord server.

Next steps

Once you've added IgKnite to your Discord server, we can continue on with the setup process.

Role-locking

Most moderation Discord bots lock certain features to certain individuals, roles or permission overrides. IgKnite currently handles permissions using roles, and to be precise, you'll have to create two roles:

• BotMod for moderators.
• BotAdmin for administratiors.

These two roles will help unlock and trigger certain moderation commands for the people you choose to give these roles to. Make sure to carefully select and append the roles. IgKnite doesn't really need much more setup than this!

Using the commands

This step is quite familiar to those who are already using Discord bots with slash commands out there. But for those who still don't know, you will need only one prefix key to access all the slash commands for the bots on your server.

• Simply press / and you'll be greeted with a selection menu on top of your text box.
• Choose a command and fill in the options accordingly.
• Enter!

Hosting

This chapter describes how to host IgKnite on your own machine. It covers everything from creating project credentials to experimenting with two different ways to run IgKnite!

Preparation

Cloning the repository

Before we continue on with the upcoming procedures, let's make sure we actually have the project downloaded.

In order to clone IgKnite directly from GitHub, make sure you have Git installed. Then, run the following command:

# using HTTPS
$ git clone https://github.com/IgKniteDev/IgKnite.git

# using SSH
$ git clone git@github.com:IgKniteDev/IgKnite.git

# using the GitHub CLI
$ gh repo clone IgKniteDev/IgKnite

As you can see, there are actually three different commands for you to choose from. This is typically provided by GitHub right at the repository home page, but we've written it here so you don't have to search. :P

Creating the bot

Like actual Discord accounts, bots also need to be created in a rather fancy manner. If you have created Discord bots previously then this step might be familiar.

If you'd like to get into more detail about this topic, kindly check out this article from Discord which explores how to create, add and manage a Discord bot from scratch. But if you're (a bit) impatient, you can follow along the short path given below:

1. Navigate to Discord Developer Portal.
2. Create a new application.
3. Choose Bots from the sidebar and enable it.

That's it! You now have a new Discord bot; ready to be alive.

But this bot is still not in your server. In order to add the bot to your personal Discord server or have a friend use it:

• Choose OAuth2 from the sidebar and choose URL Generator.

• Click on bot and application.commands from the scopes view.

• Make sure you have these permissions ticked:

  

• Copy the link generated below and open it in a new tab.

• Choose your server, fill in the CAPTCHA and voila!
  

Getting the files ready

Let's open the cloned folder using the following command:

# Open and list all the files.
$ cd IgKnite && ls

You'll see a bunch of file names appearing on your terminal. One of them is .env.sample and your very first steps will be to:

• Rename .env.sample to .env and save.
• Open the renamed file with your favorite code editor.

Here are some commands to help you:

# copying
$ cp .env.sample .env

# opening it within nano
$ nano .env

Knowing the secrets

The file you just renamed and opened is the primary file where you'll be storing all the credentials and secrets. This is called a local environment file.

We're assuming you're seeing something similar to this on your code editor:

DISCORD_TOKEN=
DISCORD_OWNER_ID=
SPOTIFY_CLIENT_ID=
SPOTIFY_CLIENT_SECRET=

These are the four environment variables which are all mandatory for running IgKnite. Two of them can be obtained from the Discord Developer Portal and the other two from Spotify for Developers respectively.

Getting the environment variables

Now we can actually go and fetch all the secrets we need. If you've previously created a Discord bot then you already know how to obtain the first two variables. If not, don't worry, that's what the documentation is for.

• Navigate to the Discord Developer Portal web page.
• Click on the application we had created previously.
• Choose Bots from the sidebar.
• Copy the token.
• Paste it inside the DISCORD_TOKEN variable.

That's one done! If you'd like to obtain the other environment variable originating from Discord, then that's pretty easy too. You'll just have to copy and paste the ID of your Discord account in the field.

Speaking of the variables related to Spotify, those are relatively easy to get as well. To get the rest of the required secrets:

• Navigate to the Spotify for Developers web page.
• Choose Dashboard from the top bar and click on 'Create an App'.
• Copy the Client ID from the app's window and paste it inside the SPOTIFY_CLIENT_ID variable.
• Similarly, copy the Client Secret and paste it inside the SPOTIFY_CLIENT_SECRETS variable.
  

That's basically it! Now we are fully ready to run IgKnite.

The Docker Way

The first and easiest way of self-hosting IgKnite is by using Docker. For those who don't know, Docker basically uses containers and images to virtualize an entire operating system within another. This way, you don't need to worry about your applications failing on other platforms if it works on your own machine. Interesting, right?

Getting familiar

Previously, we ran a command to open and list all the files within IgKnite's directory. Let's run the command again in a new terminal window if you have closed the previous one:

# Open and list all the files.
$ cd IgKnite && ls

Notice something? Most Docker uses have already noticed a Dockerfile within the directory. This file works as a blueprint for building Docker images.

Preparing

This time, your very first step will be to install Docker onto your computer. Once installed, open it and follow along with the additional setup procedures thrown by the app. This would be a great time to learn about Docker by watching this 100-seconds video made by Fireship if you already don't use this tool already.

You might also need Docker Compose if you'd like to manually build a Docker Image for IgKnite and run it. For Windows and macOS, it comes bundled with the original Docker package. However, you'll have to install it separately on Linux distributions.

Instructions

• Method 1: Pull from our official GitHub Package registry.

$ docker pull ghcr.io/igknitedev/igknite:latest

• Method 2: Manual Building

# building the image
$ docker-compose build

# running it
$ docker-compose up

# list running containers
$ docker ps --all

Enjoy!

You should now see logs appearing on your terminal window, eventually displaying the total number of shards and servers IgKnite is connected to. This means you've officially self-hosted IgKnite with Docker!

The Manual Way

If you're not into Docker or you'd like to set up IgKnite for coding on it, this is the perfect place to get your hands dirty and run IgKnite with full manual management on the dependencies.

Preparation

Unlike the Docker setup method, this one requires a fair bit of dependencies to be installed beforehand.

• You will need a Python installation of version 3.11 or higher.
• You will need a native installation of ffmpeg for running music commands.

For now we'll only set up these two, but later we'll install more using a package manager.

Installation

Let's navigate to the directory where IgKnite resides, using the previous command:

$ cd IgKnite

Now that we're in, it's time to set up a virtual environment for Python. Since we don't want to get our hard drives dirty in the process of running the project, we'll use such environments to centralize all of the Python packages inside the directory.

We'll be using the venv command provided built-in with Python like this:

# creating the environment
$ python3 -m venv venv

# activating it
$ source venv/bin/activate

The following command will create a new folder named venv within IgKnite's project directory. This folder will contain all of the packages and symlinks we need.

Once done, we can install the required Python packages using pip:

# the -r flag specifies a file path
$ python3 -m pip install -r requirements.txt

Enjoy!

This might take a while, but once all of the installation procedures are complete, we can finally run igKnite using this tiny command right here!

$ python3 main.py

Development Setup

For those who'd like to add new features to IgKnite using code, low-code or even non-code contributions, this is the perfect chapter to follow along.

Preparation

The preparation for hosting sub-chapter discusses the primary ways to self-host IgKnite on your local machine. Make sure to read and apply the contents of it properly and then continue reading towards the manual hosting sub-chapter as well to set up all of the necessary dependencies.

Code Style

In order to maintain a proper and managed syntax, this project has two different packages:

• flake8 for linting
• black for formatting

# installation
$ python3 -m pip install flake8 black

For those who use Visual Studio Code, the project also contains configuration for the isort extension for automatically organizing imports on every save.

Adding commands

Have an idea? Let's build it!

Note

It's noteworthy that your contributions must follow the Code of Conduct included with the repository. Make sure to read it before creating any unnecessary changes within the code. We'd love to see your ideas come to life within IgKnite!

The Steps

In order to add new commands to the project, you must follow through the three mandatory steps mentioned below:

1. Choosing a "Cog"

On both discord.py and disnake, categories of commands are referred to as "cogs". There are six different cogs which come built-in with IgKnite located in the cogs subdirectory. Navigate to your chosen one and have a look at the source code before making any changes.

2. Creating the command

Once you have decided which cog to add your command to, we can start writing some code now!

Discord has three types of commands:

• Slash commands can be used by pressing / and then typing the command.
• User commands can be used by right-clicking on a user's avatar and then selecting 'Apps'.
• Message commands are similar to user commands but need you to click on a message instead of someone's avatar.

Below is an example of a very basic slash command which greets a server member. You'll be using such syntax in most of your commands.

# sample imports
import disnake
from disnake.ext import commands
from disnake.ext.commands import Param  # used for options

# the cog
class SomeCog(commands.Cog):

...

	@commands.slash_command(
		name='greet',
		description='Greets a member!',
		dm_permission=False  # disables the command inside DMs
	)
	async def _greet(
		self,
		inter: disnake.CommandInteraction,
		member: disnake.Member = Param(description='Mention the server member.')
	) -> None:
		await member.send(
			f'Hey there! Welcome to {inter.guild.name}.'
		)

On the other hand, you can also write code and deploy to all three types of commands at once! In the example given below, we've tried to make a ban command that uses the very same logic for deploying itself in three forms:

# Backend for ban-labelled commands.
# Do not use it within other commands unless really necessary.

async def _ban_backend(
	self,
	inter: disnake.CommandInteraction,
	member: disnake.Member,
	reason: str = 'No reason provided.'
) -> None:
	await inter.guild.ban(
		member,
		reason=reason
	)
	await inter.send(f'Member **{member.display_name}** has been banned! Reason: {reason}')


# ban (slash)
@commands.slash_command(
	name='ban',
	description='Bans a member.',
	dm_permission=False
)
@commands.has_any_role(LockRoles.mod, LockRoles.admin)
async def _ban(
	self,
	inter: disnake.CommandInteraction,
	member: disnake.Member = Param(description='Mention the server member.'),
	reason: str = Param(
		description='Give a reason for the ban.',
		default='Default reason.'  # having a default value makes it optional
	)
) -> None:
	await self._ban_backend(inter, member, reason=reason)


# ban (user)
@commands.user_command(
	name='Ban',
	dm_permission=False
)
@commands.has_any_role(LockRoles.mod, LockRoles.admin)
async def _ban_user(
	self,
	inter: disnake.CommandInteraction,
	member: disnake.Member
) -> None:
	await self._ban_backend(inter, member)


# ban (message)
@commands.message_command(
	name='Ban',
	dm_permission=False
)
@commands.has_any_role(LockRoles.mod, LockRoles.admin)
async def _ban_message(
	self,
	inter: disnake.CommandInteraction,
	message: disnake.Message
) -> None:
	await self._ban_backend(inter, message.author)

...

3. Test and deploy

Once you are done making your changes, push them to your fork and create a valid pull request. Here's an example pull request which you can have a look at to learn about the pattern.

The pull request must pass the given workflows (the ones mentioned earlier) and receive a green 'check' symbol to qualify for a merge. We hope you'll do your best to gain it!

Command Reference

IgKnite currently has approximately 48 available bot commands, roughly distributed among five categories. All the commands are built on Discord's bleeding edge API and use the latest features.

Legend:

• <required> [optional]

• 🔪 BotMod

• ⚔️ BotAdmin

The following is a list of all the available commands (updated: May 22, 2023).

⚙️ General

/avatar [member]

Displays your avatar / the avatar of a server member.

/ping

Shows the bot's current response time and more.

/help

Get to know more about IgKnite!

🔎 Inspection

/guildinfo 🔪⚔️

Shows all important information about the server.

/userinfo [member] 🔪⚔️

Shows all important information on a user.

/roleinfo <role> 🔪⚔️

Shows all important information related to a specific role.

/invites 🔪⚔️

Displays active server invites.

/revokeinvites [member] 🔪⚔️

Revokes invites. By default this removes all invites but you can choose a server member.

/audit [limit] 🔪⚔️

Views the latest entries of the audit log in detail.

🖌 Customization

/makerole <name> [color] ⚔️

Create a new role.

/assignrole <member> ⚔️

Assign a role to a server member.

/removerole <role> ⚔️

Revome a role from the server.

/makeinvite [max_age] [max_uses] [reason] 🔪⚔️

Create an invitation link to the server.

/nick <member> <nickname> 🔪⚔️

Change nickname of a member.

/makechannel <name> [category] [topic] ⚔️

Create a new text channel.

/makevc <name> [category] ⚔️

Create a new voice channel.

/makecategory <name> ⚔️

Create a new channel category.

/removechannel <channel> ⚔️

Remove a channel from the server.

/reset ⚔️

Resets the current channel.

/afkvc [channel] [timeout] ⚔️

Configures the inactive (AFK) channel for the server.

🔨 Moderation

/ban <member> [reason] 🔪⚔️

Bans a member from the server.

/softban <member> [reason] 🔪⚔️

Temporarily bans members to delete their messages.

/unban <member> 🔪⚔️

Unbans a member from the server.

/kick <member> [reason] 🔪⚔️

Kicks a member from the server.

/timeout <member> [duration] [reason] 🔪⚔️

Timeouts a member.

/purge [amount] [onlyme] 🔪⚔️

Clears messages within the given index.

/ripplepurge <member> [amount] 🔪⚔️

Clears messages that are sent by a specific user within the given index.

/snipe 🔪⚔️

Snipes messages within 25 seconds of their deletion.

/senddm <member> <msg> 🔪⚔️

Send DM to specific users.

/pins

Shows all pinned messages in the current channel.

/clearpins 🔪⚔️

Clears all pinned messages in the current channel.

/slowmode <seconds> 🔪⚔️

Sets slowmode for the current channel.

/banword <keywords> ⚔️

Add keywords to ban.

/clearbannedwords ⚔️

Clears the list of banned keywords added by IgKnite.

/showbannedwords ⚔️

Shows the list of banned keywords added by IgKnite.

/clearnicks ⚔️

Clear everyone's nickname in the guild.

🎧 Music

/play <keyword> [boosted]

Enqueues playable stuff (basically sings you songs).

/playrich [member]

Tries to enqueue a song from one's Spotify rich presence.

/pause

Pause the currently playing song.

/resume

Resume the currently playing song.

/stop

Stops playing songs and clears the queue.

/join [channel]

Joins the voice channel you're in. You can also specify which channel to join.

/leave

Clears the queue and leaves the voice channel.

/volume <volume>

Sets the volume of the current track.

/now

Displays an interactive control view for the current song.

/skip

Vote to skip a song. The requester can automatically skip.

/queue

Shows the player's queue.

/rmqueue <index>

Removes a song from the queue at a given index.