A discord bot for young ornithologists. This bot is designed to help people practice the identification portion of the Science Olympiad Ornithology event.
The prefix for this bot is b!
. Use b!help
to get a list of commands, and b!help [command]
for help with a specific command. A demo of the bot is available here.
For help with the bot, feature requests, or any other questions, please join our support server here. You can also add the bot to your own server, or use the bot too.
By using this bot or adding it to a server, you agree to the Terms of Service, Privacy Policy, and Community Code of Conduct.
If you have previous programming experience and would like to help us add features or fix issues, feel free to make a pull request. Our code probably isn't of the highest quality, so we value any suggestions you may have.
If you find an issue with the bot, please report it in the support server instead of opening a Github issue.
To run the bot locally, you'll need to install some software first.
- Clone the repo locally with
git clone https://github.com/tctree333/Bird-ID.git
. - Install a local Redis server by running
chmod +x install-redis.sh && ./install-redis.sh
. Source. Start your Redis server withredis-server
. We're using Redis 4.0.14. - Copy the file
.env.example
to.env
(DO NOT edit.env.example
directly) - If using a remote redis server, or an address other than the default
redis://localhost:6379
, setSCIOLY_ID_BOT_LOCAL_REDIS
tofalse
and changeSCIOLY_ID_BOT_REDIS_URL
appropriately - Optionally, you can create a sentry.io account, which we use for error monitoring. Set
SCIOLY_ID_BOT_USE_SENTRY
totrue
andSCIOLY_ID_BOT_SENTRY_DISCORD_DSN
to your Sentry DSN in.env
. - Register a bot account on the Discord Developers Portal. To do so, create a new application. Name your application, then navigate to the
Bot
section, and add a bot. Change your application name if necessary. In.env
, updateSCIOLY_ID_BOT_TOKEN
with your bot token (Bot
section) and updateSCIOLY_ID_BOT_OWNER_IDS
to a comma separated list of user-ids of owners. You can find your user-id by enabling Developer mode in Discord Settings > Appearance, right clicking on your username in the Member List, and selectingCopy ID
. - Generate your bot invite link by going to the
OAuth2
section in the Discord Developers Portal. Selectbot
as the scope, and checkSend Messages
,Embed Links
,Attach Files
, andManage Roles
in theBot Permissions
section. Copy the generated link (it should look like this:https://discord.com/api/oauth2/authorize?client_id=(Your Client ID)&permissions=268486656&scope=bot
). Add the bot to your own server by pasting the link into your browser. - Install any necessary packages with
pip install -r requirements.txt
. You may also want to setup a python virtual environment to avoid package conflicts before installing packages. - You are now ready to run the application! Start the bot with
python3 -m bot
. Make sure you're on Python version 3.7.
The bot can also attempt to backup the Redis database to a set Discord channel. To enable this, set SCIOLY_ID_BOT_ENABLE_BACKUPS
to true
and SCIOLY_ID_BOT_BACKUPS_CHANNEL
to the channel id of a channel the bot has access to in .env
.
If you need help or have any questions, let us know in our Discord support server.
If you are having issues running the bot locally, here are some tips and common issues people run into.
- Make sure you're on Python 3.7, since we're using some language features only available in version 3.7.
- If you're having issues with Redis, make sure you're on version 4.0.14 or later. If you're still having issues, see the Redis documentation.
- Common Redis errors include:
ValueError: Redis URL must specify one of the followingschemes (redis://, rediss://, unix://)
- Make sure theSCIOLY_ID_BOT_LOCAL_REDIS
environment variable is set totrue
if you're using a local Redis server. If you're using a remote Redis server, or a server with a different address, make sureSCIOLY_ID_BOT_LOCAL_REDIS
isfalse
and theSCIOLY_ID_BOT_REDIS_URL
environment variable is set correctly.redis.exceptions.ConnectionError: Error 61 connecting to localhost:6379. Connection refused.
- Make sure your Redis server is actually running. You can start it withredis-server
from theredis-stable
directory.
- If your error message mentions errors with the
covid
cog or a coronavirus API and you aren't terribly concerned about this feature, disable the cog manually by removingbot.cogs.covid
fromSCIOLY_ID_BOT_EXTRA_COGS
in.env
. - If your error is about missing Discord Permissions, make sure your bot account has permission to send messages, send files, embed links, and manage roles in that channel.
Having other issues not listed here? Ask in our Discord support server and we will do our best to solve the problem.
The main bot application uses the bot folder.
__main__.py
is the application start point, withfunctions.py
containing assorted functions assisting with downloading bird files and other commonly used functions.- The
data
folder stores bird lists, withdata.py
managing those lists along with logging and database tasks. - The
cogs
folder contains the bot commands themselves, with each file being a different collection of commands (a category inb!help
). - The
media
folder contains assorted image files for achievement badges and other things.
Bot unit tests uses the test
folder. Currently, test coverage is quite poor and these tests are mostly just for fun and learning. If you would like to contribute to tests and increase test coverage, that would be greatly appreciated.
discord_mock.py
contains classes to replicate discord.py functionality.test_{COG NAME}.py
contains the tests for the respective cog.
The web API uses the web
folder. Currently, development of the web API is paused.
.travis.yml
is the config file for Travis CI, which runs the tests. travis_pr_script.sh
is a script for Travis that installs and runs a local Redis instance for PRs, since private environment variables in PRs are disabled for security reasons.
runtime.txt
and Procfile
are files used by Heroku, where we host the bot.
.env.example
is the template for the .env
file (which itself cannot be tracked by git).