For HackKU24, we launched helper duck! helper duck is a discord bot that functions as a system for hackers to submit help tickets to mentors.
Since then helper duck has been improved upon and changed to support HackKU25 and HackKU26
You will need Python 3.12+, uv, and SQLite3 installed on your system.
uv sync
No uv? A
requirements.txtis provided as a fallback for plain pip + venv setups, but uv is strongly recommended.python3 -m venv .venv && source .venv/bin/activate pip install -r requirements.txt
sqlite3 database.db < db_init.sql
Replace database.db with whatever name you'd like to use for the database file.
Create a .env file in the project root and fill it out as follows:
DB_FILE=<name of database file from above>
ANNOUNCEMENT_ENDPOINT=<endpoint to send announcements to>
MENTOR_CHANNEL_ID=<mentor private channel id from discord>
HELP_CHANNEL_ID=<channel for helper duck to create threads in>
ANNOUNCEMENT_CHANNEL_ID=<channel for the hackathon announcements>
GUILD_ID=<id of your hackathon's discord server>
MENTOR_ROLE_ID=<id of the role only mentors have in discord>
ORGANIZER_ROLE_ID=<id of the role only organizers have in discord>
WELCOME_MESSAGE_ID=<id of the welcome message in the help channel>
COUNTING_CHANNEL_ID=<id of the counting game channel>
API_TOKEN=<discord api token>
ANNOUNCEMENT_SECRET=<secret for announcement endpoint authentication>
COUNTING_START=0
A couple of notes:
- You can find the various IDs of objects within Discord by turning on developer mode in your Discord client. Right-clicking a server, role, or channel will reveal a new option to copy the ID.
- The Discord API token can be generated by creating a new app and bot in the Discord developer portal. Make sure to invite helper duck to your server with the right intents!
COUNTING_STARTis optional and defaults to0.
uv run main.py
The Dockerfile can be used to create a docker image to run helper duck anywhere a docker container can run! There are plenty of cloud options and self-hosting is fairly easy.
Happy hacking! 🍻