Build and deploy a Java Discord bot with Spring Boot

Discord bots are one of the easiest ways to automate community tasks, build moderation tools, create reminder systems, and add custom workflows to Discord servers. For Java developers, the hard part is usually not the bot logic itself. It is the repetitive setup around authentication, command structure, project wiring, and deployment.

That is where Basely fits in. It gives you a practical Spring Boot foundation for a Discord bot so you can focus on the actual features instead of rebuilding the same base every time.

What basely is for

Basely is a Java Discord bot boilerplate designed for developers who want a clean starting point. It is useful for moderation bots, utility bots, reminder bots, community assistants, and learning projects built with JDA and Spring Boot.

The idea is simple: instead of starting with an empty project and deciding everything from scratch, you begin with a structured codebase that already has a clear path for commands, events, services, and configuration.

Before you start

• Java 21 or newer
• Maven installed locally, or the Maven wrapper included in the project
• A Discord account
• Access to the Discord Developer Portal
• A VPS with Java installed for production deployment

1. Create your Discord application

Start by opening the Discord Developer Portal. From there, create a new application and give it a name that matches your bot.

Once the application exists, open the Bot tab and click Add Bot. Discord will create the bot user attached to your application.

Copy the bot token carefully. This token is the secret key your application uses to authenticate with Discord. Never commit it to GitHub and never paste it directly into public files.

Recommended settings in the developer portal

• Enable the bot user under the Bot tab
• Copy the token and store it securely
• Turn on only the privileged intents you actually need
• Keep the application name and avatar consistent with your project brand

2. Invite the bot to your server

To test the bot locally, invite it to a Discord server where you have permission to manage integrations. Use the OAuth2 URL generator inside the Discord Developer Portal.

Select the bot scope and, if your project uses slash commands, also select applications.commands. Then choose the permissions your bot needs. For a test server, start with the minimum required permissions and expand later.

After generating the invite link, open it in your browser and add the bot to the server.

3. Configure basely locally

Then configure the environment variables your Spring Boot Discord bot needs. The exact variable names depend on your code, but a clean setup usually looks like this:

spring.application.name=Basely
server.port=8080

discord.token=${DISCORD_BOT_TOKEN}
discord.guild-id=${DISCORD_GUILD_ID}

Adjust these names to match your implementation if your project uses a different configuration style.

4. Run the project locally

Run the project as a Spring Boot application from your IDE. If your Discord bot token is configured correctly, the bot should connect immediately.

If the bot logs in successfully, you should see it connect to Discord and register the configured commands or listeners.

5. Prepare the VPS

For production deployment, run your Java Discord bot on a VPS instead of your local machine. This keeps the bot online continuously and provides a stable runtime environment for long-running background processes.

Make sure docker compose is installed on your VPS.

docker compose version

If not then install docker + docker compose.

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo $VERSION_CODENAME) stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update

sudo apt install -y docker-ce docker-ce-cli containerd.io \
docker-buildx-plugin docker-compose-plugin

sudo systemctl start docker
sudo systemctl enable docker

sudo usermod -aG docker $USER
newgrp docker

6. Run the bot in a Docker container

On the VPS, create docker-compose.yml file:

version: "3.9"

services:
    mysql:
    image: mysql:8.0
    container_name: basely-mysql
    restart: always

    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: boiler_agent_discord_bot_db

    volumes:
      - mysql_data:/var/lib/mysql

    ports:
      - "3306:3306"

  basely:
    image: eclipse-temurin:21-jdk
    container_name: basely-bot
    restart: always

    depends_on:
      - mysql

    working_dir: /app

    volumes:
      - ./basely.jar:/app/basely.jar

    env_file:
      - .env

    command: ["java", "-jar", "/app/basely.jar"]

    environment:
      SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/boiler_agent_discord_bot_db
      SPRING_DATASOURCE_USERNAME: root
      SPRING_DATASOURCE_PASSWORD: rootpassword

    logging:
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  mysql_data:

and .env file like this:

DISCORD_TOKEN=your_discord_bot_token_here
SPRING_PROFILES_ACTIVE=prod

Run basely with docker compose

docker compose up -d

Common issues