CodiLime's vote bot for Slack
This bot allows to grant points to other users. Points can be granted in 3 categories, accordingly to CodiLime Manifesto:
- Team up to win
- Act to deliver
- Disrupt to grow
- Refactor of code in
utilsandviewswould be nice. - If gathering data about winners through Slack commands feels clunky - in
/admin/add custom views and graphs with this data.
This repository uses poetry to manage dependencies.
You can install dependencies from requirements txt files from requirements dir, as usual:
python -m venv venv
source venv/bin/activate
pip install -r requirements/prod.txtIf you need to make any changes - use poetry to ensure control over dependencies. Then if you wish to generate new, updated requirements txt files use:
poetry export --without-hashes --format=requirements.txt > requirements/prod.txt
poetry export --without-hashes --format=requirements.txt > requirements/dev.txt --dev docker-compose -f docker-compose.tests.yaml up test-app --buildAlternatively you can run tests with Python. You'll need virtual env set, and requirements installed, and with that
everything should just run. Without the .env file, Slack API configuration, or rest of this readme:
python manage.py testTo check tests coverage run:
coverage run --source='./bot_app' manage.py test --verbosity=3 && coverage report -m- You'll need a Slack workspace to work on with your instance of bot. You can create a new one or invite yourself to our test workspace.
- Create account on Slack API, create a new app from scratch, pick a workspace on which you want to install your app.
- Go to OAuth & Permissions and set bellow scopes in Bot Token Scopes:
channels:history
chat:write
commands
users:read
- Scroll up and click Install to Workspace, after installation you should receive Bot User OAuth Token in
xoxb-...format - After that you can either run app locally or from Docker container.
- Create new, empty PostgreSQL database
- In project's root create
.envfile:
SECRET_KEY=[django secret key, unique and unpredictable value, whatever you come up with]
DATABASE_URL=your database url in postgres://USER:PASSWORD@127.0.0.1:5432/DATABASE format
SIGNING_SECRET=[Signing Secret from Slack API -> Basic Information -> App Credentials section]
SLACK_BOT_TOKEN=[xoxb Bot User OAuth Token from Slack API -> Install App section]
ENABLE_SCHEDULER=0 # Enable for production.
DEBUG=1
- With all that completed you should be able to run migrations and start the app:
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver- App should be available at http://127.0.0.1:8000/
- For full functionality you'll have to set up endpoints in Slack API.
- In project's root create
.envfile:
SECRET_KEY=[django secret key, unique and unpredictable value, whatever you come up with]
DATABASE_URL=postgres://postgres:postgres@db:5432/votebot # URL to db container.
SIGNING_SECRET=[Signing Secret from Slack API -> Basic Information -> App Credentials section]
SLACK_BOT_TOKEN=[xoxb Bot User OAuth Token from Slack API -> Install App section]
ENABLE_SCHEDULER=0 # Enable for production.
- If it's the first run, or you removed
databasevolume you have to migrate DB and create superuser first:
docker-compose run --entrypoint python app manage.py migrate
docker-compose run --entrypoint python app manage.py createsuperuser- After that use
docker-compose upcommand to run the containers - App should be available at http://127.0.0.1:8000/
- For full functionality you'll have to set up endpoints in Slack API.
Static files
With Docker app is served through Nginx, like it would on production server. Because of that static files are also
server by Nginx. If static files are out of date or not working correctly try running python manage.py collectstatic
to rebuild static directory, and then rebuilding Nginx image while running the stack with docker-compose up --build.
Endpoints to handle user's slash commands:
/about - information about the awards program
/vote - show voting form
/check-votes - check your previous votes from this month
/check-points - check points you received this month
/check-winners - check this month's winner, if you have permissions
Other endpoints, required for app's functionality:
/interactive - handle interactions with modals, buttons, etc., in our case receive subbmited voting modal
/event/hook/ - handle miscellaneous events, like somebody mentioning our awards program in a message
For all of this to work our app has to be visible to the world (and Slack API). To achieve that Slack documentation recommends
to use Ngrok as a local proxy.
Only change being to run it on the same port that our app is running now (probably 8000).
Having forwarded ngrok URL from https://abcd-01-23-45-678.eu.ngrok.io to our machine we can set up endpoints in the Slack API.
For slash commands to work you have to create each command in the Slash Commands tab.
Any commands that were not added will not work. To add /about command you'd have to set it up like this:
Command: /about
Request URL: https://abcd-01-23-45-678.eu.ngrok.io/about
Short description: Description of awards program.
To enable voting you have to set up /vote slash command and enable interactivity for your app.
To enable interactivity you have to go to Interactivity & Shortcuts tab, toggle the switch
and add your local proxy endpoint: https://abcd-01-23-45-678.eu.ngrok.io/interactive
To enable events you have to go to Events Subscriptions tab, toggle the switch
and add your local proxy endpoint: https://abcd-01-23-45-678.eu.ngrok.io/event/hook/.
App has to be running to allow Slack to check the endpoint, and trailing slash is important!
After that you'll have to add new event message.channels in Subscribe to bot events and save changes.
App has a scheduler that is responsible for running periodic jobs. It can send reminders, announce winners, sync users
from slack, and so on. It's running in separate thread to not block the main application.
Scheduler's jobs can be edited in the bot_app/scheduler/scheduler.py file, in
6C1E
the schedule_jobs function.
Scheduler is disabled for development by default, but it should be enabled on production environment.
Set ENABLE_SCHEDULER=1 environmental variable to enable the scheduler.
To check winners for current month use /check-winners slash command. Additionally, there is a job scheduled
that will automatically post message about winners on the last day of the month.
Although to be possible for user to receive that message the checkbox is hr in the /admin has to be selected
for that user. Otherwise, the user will receive message about lacking the permissions to check winners.