btreecat/xkcd-4-slack repository overview

⁠xkcd for Slack

A FOSS service that you can self-host, providing /xkcd commands in Slack.

⁠Getting started

⁠Requirements

⁠Deployment

• Docker (to run the service)
• Slack (to interact with the service using /commands)
• Google Programmable Search API Access

⁠Development

• Python 3.10+
• pip install -r requirements.txt
• Slack
• Google Programmable Search API Access

⁠Sign up for Slack

You will need a SLACK_BOT_TOKEN and a SLACK_SIGNING_SECRET which you can get when you create a slack app.

⁠Sign up for Custom Search

You will need a Google Programmable search⁠ setup, and the associated SEARCH_ENGINE_ID and CUST_SEARCH_KEY.

⁠Sites to Exclude

Under the Advanced option for the Programmable Search Engine it is recommended to add the following exclusions:

⁠Running the Service

This service needs to be hosted at a publicly reachable location, so any machine with a public IP will work.

⁠Docker

There is an included Dockerfile for building the image and a docker-compose.yml for building and running the service.

$ docker-compose up --build

Prebuilt Docker container: btreecat/xkcd-4-slack⁠

⁠.env Key:Value

⁠Usage

The bot responds to /xkcd commands or to @xkcd-4-slack mentions (but only with helper text in a mention).

⁠Features

• Comic by ID
• Random Comic
• Latest Comic
• Key-word Search
• Approve-before-post Workflow

⁠Comic by ID

Given a comic ID number, fetch that specific comic.

/xkcd 386

⁠Random Comic

Pass the random flag (-r or --random) to get a random comic.

/xkcd -r

⁠Latest Comic

Pass the latest flag (-l or --latest) to get the latest comic.

/xkcd -l

⁠Key-word Search

Uses DuckDuckGo to site search xkcd.com for the right comic. By default this will pick the first valid result. Using the -r or --random flag after your search terms will force the choice to be random rather than the first one.

/xkcd exploit

or

/xkcd sys admin -r

⁠Approve-before-post Workflow

Just like Giphy, this plugin will preview the image only to the person running the /xkcd command. From the preview, you can choose to Approve or Reject the image selected.

When searching, there is also the option to select Spin which will re-run the search (stateless), but with the -r random flag added on to force a random choice from the results list rather than just picking the first one.

⁠Roadmap

• Possibly find a different search solution Moved to Google Custom Search
• Possibly Write a UA generator to come up with randomized UA. No longer using UA based websearch wrapper

⁠Testing

Using doctest⁠ for testing.

From the repo root:

$ python -m doctest -v src/utils.py

⁠Authors and acknowledgment

• Stephen Tanner - Author
• Bob Vail - Motivation
• Randall Munroe - xkcd

⁠License

MIT

⁠Project status

Mostly complete. Bug fixes as needed.