Matsubo parses Japanese 祭り 🎏 (Japanese for "festival") and other events from different sources and uses Discord to summarize all event details.
Events are filtered by region and users are reminded at the start of an event. Currently, events are parsed from the following sources:
Source | URL |
---|---|
tokyocheapo.com | |
japancheapo.com |
!! Disclaimer
These websites do not belong to this repository, nor does this repository have a relation with any of these websites. Matsubo will always direct you to the corresponding source where the event was found, not a direct link to the event website itself. This is to honor the great people working on the mentioned websites.
Matsubo only serves the purpose of summarizing events from different sources, and reminding people when an event has started.
Before you follow the steps below, make sure that you have a
Discord Bot Token
by following the guide how to get a discord bot token.
Since Matsubo is a Discord bot that should react to user input anytime, Matsubo should also run at any given time. Below are two options explained to run Matsubo.
Heroku is a hosting website for programs running 24/7 or between specified time intervals. They have a free hobby-dev tier, and more advanced tiers for production.
To host Matsubo on their server, follow these steps:
- Create an account at heroku.com
- Deploy by clicking on this button:
During Deployment, you will be asked to fill in a few API Keys. - At the main page of your Matsubo application, next to the Dyno formation, click on
Configure Dynos
and turn it on to run Matsubo!
That's all! 🎉
If you want to run Matsubo on your local device or another hosting service, first install the necessary software (if you haven't yet):
- Install PostgreSQL and a viewer (for example pgAdmin).
- Install
python
andpip
(in case you haven't yet). Also ensure that you havepipenv
installed with:pip install pipenv
- Open
pgAdmin
(or the other viewer you chose to use) and first do the initial settings (better use the default settings) to create a login access. Then, create a database with the namematsubo
.
Then, follow these steps:
- Download this repository and unzip it into a folder you like, or clone it with the following command:
git clone https://github.com/makokaz/matsubo.git
- Copy the file
example.env
from the folderexample/
into the main folder (same folder wherebot.py
is) and rename it to.env
. Open it and fill in the API Keys. - Install all necessary package-requirements specified in the
Pipfile
by typing in a console:pipenv install
- Activate your pipenv shell and initialize the postgres database. To do this, type
then
pipenv shell
python -m cogs.utils.database create
- To run Matsubo, simply type:
pipenv run python bot.py
That's all! 🎉
In order to login to your bot account, Matsubo needs a Discord Bot Token
(refer to how to get a discord bot token).
- If you chose to host Matsubo on Heroku, you will be asked during deployment to set the API keys. Open the file example.env and simply copy all values you will be asked during deployment. If you will be asked for
BOT_TOKEN
, insert your Discord Bot Token you obtained from how to get a discord bot token. - If you chose to follow the method on running Matsubo on a Local PC, simply insert the
Discord Bot Token
in the file.env
where you can findBOT_TOKEN = XXX
(replace it withXXX
).
To get your Discord BOT_TOKEN
, follow these steps:
- Go to https://discord.com/developers/applications and click on
New Application
. - Do the initial settings (add a profile picture, ...). This is your Bot Developer page.
- In the left panel, click on
Bot
and then onAdd Bot
. - Below Token click on
Copy
to copy yourBOT_TOKEN
.
In order to let the bot join to a Discord Server, on your Bot Developer page:
- Click on
OAuth2
in the left panel and scroll down until you see the Scopes settings. - In Scopes, tick
bot
, and in the new bot permissions settings tickAdministrator
. - Copy the URL in Scopes and open it in another tab to proceed to invite Matsubo to your server.
In the following, substitute
REGION
with one of the following:
- Chubu
- Chugoku
- Hokkaido
- Kansai
- Kanto
- Kyushu
- Okinawa
- Shikoku
- Tohoku
- To subscribe a channel for where to post events, send a Discord message:
.subscribe REGION
- To unsubscribe a region to a channel, type:
.subscribe REGION
- To see all currently subscribed regions of a channel, type in that channel:
.getsubscribedtopics
- The events will clutter automatically in the channel over the days. If you want to enforce doing it NOW, type:
.scrap
Matsubo also has other commands. Type inside a channel
.help
to get an overview of all commands, and
.help COMMAND
to get help for a specific command (substitute COMMAND
with the command-name, for example scrap
).
├── cogs/ # the bot functionality goes here
├── example/ # example files to help you set up the bot and how to add functionality
└── bot.py # the main bot: handles the login process and how to load modules
Due to the module structure when using Discord's "Cogs", additional functionality is easily implemented without changing the base code. (In fact, you just need to insert a file into the
cogs/
folder without touching the base code!). For example, you can copy the file example_cog.py fromexamples/
into thecogs
folder to give the bot more functionality. That's all, really!Refer to the Discord Docs to learn the basic functionality of Discord bots.
If you want to contribute, check the current issues and discussions.
Here are a few ideas how you can contribute:
- Increase the number of sources (Facebook-events, university-websites, email-newsletters, ...)
- Fixing a broken source parser
- Adding more discord commands that fit the scheme
- Adding a website frontend to see all events in the database
As an international student coming to Japan, I was very interested in experiencing Japanese Matsuri and other types of events. Not only locally, but now in the corona pandemic many events are also held online. However, for the same reason it has become increasingly more difficult to stay up to date with event details and many of them are cancelled last minute.
After missing many events I'd have loved to attend, the idea of Matsubo was born. The name is a concatenation of the word 祭り ("Matsuri", a Japanese word for "festival" or "event") and "Bot".
Japan had a massive entry ban at the start of the pandemics 2020, prohibiting every student that aimed to study in Japan from entering the country. Due to the lack of proper information and other mispread details, we international students organized ourselves in a Discord server. This in the end resulted in using Discord as a front-end to summarize the event-details.
To this date, Matsubo still serves international students in Japan and helping them untie the chaos when it comes to events.
Even though Matsubo was originally designed for international students in Japan, this does not mean that it is exclusive to those, nor that it is only to be used in Japan. With a few modifications it can serve anyone anywhere. 😊
If you like my work and want to support me, simply buy me a coffee ☕ 😌