EventPilot is a Discord bot written in Java using the Spring Boot, Project Reactor and Discord4J library. Its primary functionality is to help users create and manage events, allowing other Discord members to sign up for these events. Whether you're organizing gaming sessions, study groups, or any other kind of event, EventPilot simplifies the process by providing a user-friendly interface within your Discord server.

Table of Contents

• Features
• About Project
  • Technologies Used
  • Lessons Learned
• Getting Started
  • Prerequisites
  • Run Application Locally
  • Setup Development Environment
• Usage
  • Commands
• Contributing
• FAQ
• License

Features

• Create and manage events within your Discord server.
• Allow members to sign up for events with a simple command.
• Display event details, including the organizer, date, time, and available slots.
• Automatic event reminders to keep participants informed.

About Project

This project began as a personal hobby, driven by my interest in reactive programming and experimentation with the Project Reactor library. Initially, it was intended for personal use within my Discord server among friends. However, over time, it evolved into a robust application with its own database, asynchronous operations, CI pipeline and much more.

Technologies Used

The project leverages the following technologies:

• Java 17 - The programming language used to develop the bot.
• Project Reactor - Library for reactive programming in Java, utilized to handle asynchronous operations.
• Discord4J - Discord API wrapper for Java, enabling seamless integration with the Discord platform.
• Spring Boot - Framework used for building Java applications, providing features such as web development, data persistence, and logging.
• PostgreSQL - An open-source relational database management system, used to store and manage event-related data.
• Flyway - Database migration tool that ensures the consistency and integrity of the database schema.
• Redis - In-memory data store used as a database and cache for efficient data storage and retrieval.
• Spring Security - Highly customizable authentication and access-control framework.
• JSON Web Token - Open standard that defines a compact and self-contained way for securely transmitting information between parties as a JSON object.
• JUnit 5 - Testing framework for Java, utilized for writing unit tests.
• Mockito - Mocking framework used for testing, providing flexibility in creating and verifying mock objects.
• Testcontainers - A Java library that simplifies the use of Docker containers for integration testing.
• Reactor Test - Testing module for the Reactor library, facilitating the testing of reactive code.
• Buildpacks - Used to build OCI-compliant images for streamlined deployment and scalability.

Lessons Learned

Throughout the development, I have gained valuable knowledge and experience in several areas. This includes working with the Discord API and Discord4J library, implementing reactive programming using Project Reactor, managing a PostgreSQL database, setting up a CI/CD pipeline, conducting comprehensive testing with JUnit 5 and Mockito, leveraging Docker containers for integration testing using Testcontainers, utilizing buildpacks for building OCI-compliant images, as well as integrating Spring Data Redis and Redis for handling custom user sessions. This project has provided me with practical hands-on experience in building a robust Discord bot and honing my skills in various Java technologies and frameworks, as well as modern deployment practices.

Getting Started

Follow these instructions to get EventPilot up and running in your Discord server.

Prerequisites

If you intend to only run bot on your local machine, you need:

• Docker

Before you begin to code, make sure your development environment have the following:

• Java Development Kit (JDK) 17 or higher
• Maven
• Docker

Run application locally in docker

One of the approach to run bot locally is that we can use docker container to run both application and database with ease. Preferable approach is to run docker-compose.yml file, to make sure all the configuration is set correctly. Example of working docker-compose.yml from this repository.

name: eventpilot
services:
  eventpilot:
    container_name: eventpilot-app
    image: havlli/eventpilot:latest
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://database:5432/eventpilot
      CACHE_REDIS_HOST: cache
      DISCORD_TOKEN: your-discord-bot-token
      JWT_SECRET: at-least-256bits-HS256-compliant-secret
    ports:
      - 8080:8080
    depends_on:
      - database
      - cache
  database:
    container_name: eventpilot-postgres
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: eventpilot
      POSTGRES_USER: havlli
      POSTGRES_PASSWORD: password
    volumes:
      - database:/data/postgres
    ports:
      - 5554:5432
    restart: unless-stopped
  cache:
    container_name: eventpilot-redis
    image: redis:7-alpine
    hostname: cache
    ports:
      - 6378:6379
    restart: unless-stopped

volumes:
  database:

1. Create or download docker-compose.yml file with same structure presented above.

Make sure you replace DISCORD_TOKEN environmental variable with your discord bot token. If you're unsure how to obtain the discord bot token check FAQ: How to acquire Discord Bot Token. Make sure that your JWT_SECRET is compliant with HS256 algorithm, if you are unsure how to create such secret just create random 32 characters long String. Generating secrets using online tools is, from security reasons, not advised.

2. Once you set your DISCORD_TOKEN variable simply run in same directory:

docker compose up -d

3. Done! After docker successfully creates and runs both containers your bot should appear online in your server and listening to commands.

Note: If your bot is not present in the server you have to first invite the bot. FAQ: How to invite newly created bot to my Discord server

Setup Development Environment

1. CD to your project folder and clone repository.

cd projectdirectory
git clone https://github.com/havlli/EventPilot.git

2. Rename .env.example file to .env and set the environmental variables, no need to export environmental variables into your system since spring-dotenv manages importing env variables from .env file.

DISCORD_BOT_TOKEN=YOUR_DISCORD_BOT_TOKEN
TEST_DISCORD_BOT_TOKEN=DISCORD_BOT_TOKEN_FOR_TESTING

Note: You can use same token for the test token, you should be running the development environment on testing discord bot instance. In case you're running dev environment on "live" discord server you can use different token for testing Discord4J and Discord API calls.

3. In terminal navigate to docker-compose-services.yml and compose postgresql container in detach mode.

cd src/main/resources
docker compose -f docker-compose-services.yml up -d

Note: If you make any changes to postgres container make sure the changes reflects in application properties application.yml as well.

4. Done! You're up and ready to start coding!

Contributing

Thank you for considering contributing to this project! Contributions from everyone are welcome.

To contribute to this project, please follow these steps:

1. Fork the repository and create a new branch for your contribution.
2. Make the necessary changes or improvements in your branch.
3. Test your changes thoroughly to ensure they do not introduce any regressions.
4. Commit your changes and push them to your forked repository.
5. Submit a pull request (PR) to the main repository. Please provide a clear and descriptive title for your PR, along with a detailed description of the changes you have made.
6. Your PR will be reviewed by the project maintainers. They may provide feedback or request further changes.
7. Once your changes have been reviewed and approved, they will be merged into the main repository.

Usage

TBA

FAQ

How to acquire Discord Bot Token

1. Navigate to Discord Developer Portal and login.
2. Click on 'New Application' to create a new application.
3. Give your application a name and click 'Create'.
4. In the left sidebar, click on 'Bot'.
5. Under the Token section, click on 'Reset Token' and then 'Copy' to copy the bot token to your clipboard.

Note: Treat your bot token as a secret and keep it secure. Do not share it publicly or commit it to version control. You can keep your token in .env file. Application loads environmental variables from that file.

How to invite newly created bot to my Discord server

To invite your created bot to your Discord server, you'll need the "Manage Server" permission or have an account with the necessary permissions on the Discord server where you want to add the bot.

1. Navigate to Discord Developer Portal and login.
2. Select your bot application.
3. In the left sidebar, click on 'OAuth2', then click on 'URL Generator'.
4. Under Scopes make sure that 'bot' and 'applications.commands' values are checked.
5. Under Bot Permissions make sure that 'Administrator' value is checked.
6. Copy the generated URL and open it in your web browser.
7. You will be prompted to authorize the bot. Select the Discord server where you want to add the bot and authorize it.
8. Complete any additional verification steps if prompted.
9. The bot will now be added to your Discord server.

License

This project is licensed under the Apache License 2.0.

The Apache License 2.0 is an open source license that allows you to use, modify, and distribute this software, both for commercial and non-commercial purposes. It provides patent and trademark protection, and requires that you include the original license notice in any derivative works.

For more details, please refer to the full text of the Apache License 2.0.