﴾ QuranBot ﴿

Disclaimers

1. Religious Disclaimer

The translations of the Ahadith provided in this application are sourced from https://hadithapi.pages.dev/, it is stated by them that: the translations are sourced from respected scholarly works. However, no translation can perfectly capture the original meaning. For critical research, we recommend consulting the original Arabic texts. [https://hadithapi.pages.dev/docs#faq]

The translations of the Holy Quran provided in this application are sourced from the Saheeh International translation. While this translation is widely trusted and highly regarded, no translation can perfectly capture the absolute depth, nuance, and meaning of the original Arabic text. The interpretations remain the scholarly effort of the translators. Users should consult qualified Islamic scholars for definitive rulings or detailed study.

2. Calculation Disclaimer

Prayer times are calculated automatically using the Adhanpy (Adhan) library. These calculations are based on high-precision astronomical equations and standard global calculation methods (e.g., ISNA, MWL). Because slight geographic and atmospheric variations exist, these prayer times are estimates. Users are encouraged to verify times visually or by listening to the local Adhan from their nearest mosque.

3. Limitation of Liability

The developers and contributors of this application shall not be held liable for any direct, indirect, or incidental damages or loss of profits arising from the use, interpretation, or reliance on the information, prayer times, or translations provided herein.

4. Open Source and Copyright Acknowledgment

This application incorporates third-party open-source software, APIs, libraries, datasets, translations, and other copyrighted materials. These components remain the property of their respective authors, organizations, and copyright holders and are used in accordance with their applicable licenses, terms of service, or permissions.

A complete and up-to-date list of third-party dependencies, services, data providers, and their respective licenses and attributions is maintained in the project's NOTICE, THIRD_PARTY_NOTICES, or LICENSES file (or equivalent documentation) and forms part of this acknowledgment.

⏾ Overview

بسم الله الرحمن الرحيم

This is an open-source, discord.py-based discord bot I made for displaying Islamic scripture.
So that it is easy to access Islamic information while using Discord.
It's written in Python and supports Docker.
And the ease of use? So easy to set up that you might forget that you ever set it up!

Amongst the reasons why I made this are:

It was narrated by Uthman that The Prophet(ﷺ) said:

"The best among you are those who learn the Qur'an and teach it." (Sahih al-Bukhari 5027)

It was narrated by Abu Huraira that The Prophet(ﷺ) said:

"When a man dies, his acts come to an end, but three, recurring charity, or knowledge (by which people) benefit, or a pious child, who prays for him (for the deceased)." (Sahih Muslim 1631)

Abu Huraira reported Allah's Messenger (ﷺ) as saying:

"He who called (people) to righteousness, there would be reward (assured) for him like the rewards of those who adhered to it, without their rewards being diminished in any respect. And he who called (people) to error, he shall have to carry (the burden) of its sin, like those who committed it, without their sins being diminished in any respect." (Sahih Muslim 2674)

---

⏾ Highlights

Features and things to implement

✓ - Working/Added/Supported	/ - Incomplete	x - Unsupported/Not Added

A command to display Qur'ânic verses.	✓
Dockerized the application.	✓
Migrated to uv package manager.	✓
Chat commands for displaying Qur'ânic verses.	✓
A command to display prayer times.	✓
Ability to set Daily verses on a specific channel.	✓
Custom quote changes to a random quote from a list of quotes periodically.	✓
A command to display Ahadith.	✓
A way to test the application using pytest.	✓
Qur'ân SQLite database.	x
A command to display Tafsîr.	x

---

⏾ Features

• /help: A slash command that displays all the available slash commands.
• /quran: A slash command that takes two arguments of integer type as input, chapter and verse, it displays a Qur'ânic verse based on the given user input. (Example: /quran chapter:2 verse:4 will display the contents of Surah Al-Baqarah, ayah number four.)
• /set-daily-quran: A slash command that takes a channel as its only argument, when ran it will set a webhook on the selected channel where it will send verses daily. (Example usage: /set-daily-quran channel:#general)
• /prayer-times: A slash command that shows the obligatory Islamic prayer times of the day based on the geographic location of the given city. (Example usage: /prayer-times city:London)
• /status: Displays system information about the bot.
• /prefix: Changes the bot's prefix for chat commands.
• /hadith: Displays a narration based on given collection and narration id.

---

⏾ Requirements

To start hosting your own QuranBot, you will need:

• Docker
• Python (Preferably version 3.11)
• PostgreSQL
• Redis

Note: You won't really need to independently install Python, PostgreSQL and Redis if you're going to use Docker.

And that's pretty much it.

---

⏾ Installation

Before Installation: Make sure you have cloned the repository either via the "<> Code" section as .zip file or via using the git clone https://github.com/AzuritilDev/QuranBot command in your terminal and then change the directory by running the cd quranbot command.

1. Docker Installation:

Short Instructions

• Create your bot
• Get the auth token
• Make and fill out your .env file
• Run docker compose up

That's it.

Detailed Instructions:

Before we begin, download the source code and extract it to a folder, you can name it something like "quranbot".
First things first, you need to create a new Discord application.
Head to the Discord Developer Portal and create your bot application.
After you have done that, you will need to get its Authorization Token
Head to Applications -> Your Application -> Overview -> Bot
Click the "Reset Token" button, it will show you the bot's token, copy the token to your clipboard.
Create an ".env" file, the structure of the .env file should be the way it's instructed in .env.example,
fill out the .env file accordingly to what you have, whether it be bot tokens, PostgreSQL usernames, passwords, etc.
or you can just edit .env.example.clean to your preferences and then name it ".env"
After that, open up your terminal, go to the root directory of the project, and run the following:

docker compose up

This will build the application, create a database and run the container.

To safely shut it down, run the following:

docker compose down

If you want to shut down the application and delete its saved data, run:

docker compose down -v

Note: Please use this command responsibly, this will power down the container AND delete the saved PostgreSQL data.

If you've done everything correctly, you should see the bot's status as online while the container is running.

If you've updated the source code for your custom build make sure to run it using:

docker compose up --build

To keep it up to date with your changes.

If you want to run the container as a background task without logs filling up your terminal, run it with the -d flag:

docker compose up -d

2. Manual Python Installation:

Short Instructions:

• Download the repository and extract it into a folder.
• Create your .env file and fill it out.
• Run uv sync --frozen --no-dev or pip install -r requirements.txt to install all the neccessary dependencies
• Run python main.py

And you're done.

Detailed Instructions:

• Make sure to get your bot's token and store it in a .txt file or somewhere else.
• Install Python version 3.11
• Download the repository, if you downloaded the .zip, extract it into a folder, name the folder something like "quranbot".
• Create an .env file in the folder, fill it out accordingly to .env.example (You can remove Docker related variables and files if you're not going to use Docker).
• Open up your terminal or command prompt, make sure you are in the quranbot folder's directory inside the terminal/command prompt
• Run uv sync --frozen --no-dev if you use the uv package manager or run pip install -r requirements.txt if you prefer using requirements.txt, make sure pip is installed in your machine (If you want to install the uv package manager, either run pip install uv if you have pip or visit here).
• Run python main.py and your bot will start running, press Ctrl+C inside the terminal when you want to stop the bot.

---

⏾ Feedback & Collaboration:

Feel free to make discussions in here and report any bugs, mistakes etc. in the issues section of the repository.

Please check the repository's guide on contributing and the code of conduct.

---

⏾ Authors:

@AzuritilDev

Made with passion & good intentions,
gifted to the Ummah ❤️

⏾ License:

Distributed under MIT license.