Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Apeuriox/lazybot-renewal/llms.txt

Use this file to discover all available pages before exploring further.

Lazybot is a self-hosted Spring Boot application. This guide walks you from zero to a running bot — cloning the source, installing the two non-Maven-central JNI libraries, filling in your credentials, seeding the database, and launching the JAR. The whole process takes under 15 minutes on a machine that already has Java 21 and MySQL.
Never commit real credentials to version control. application.yaml is listed in .gitignore by default — keep it that way. Treat your Discord token, osu! client secret, and database password as secrets and store them outside the repository (environment variables, a secrets manager, or a private config store).

​
Steps

1

Clone the Repository

Clone the lazybot-renewal repository to your local machine or server:
git clone https://github.com/Apeuriox/lazybot-renewal.git
cd lazybot-renewal
The repository includes a lib/ directory containing the two pre-built JNI JAR files that are not available on Maven Central, and a local-maven-repo/ directory used by the Maven build.
2

Install Local Maven Libraries

Lazybot depends on two JNI libraries that must be installed into your local Maven repository before the build can succeed.Rosu-JNI — osu! PP calculation engine by HollisMeynell:
mvn install:install-file \
  -Dfile=lib/rosu-jni-0.1.8.jar \
  -DgroupId=org.rosu \
  -DartifactId=rosu-java \
  -Dversion=0.1.8 \
  -Dpackaging=jar
Resvg-JNI — Rust-native SVG rasterizer by Zh_jk:
mvn install:install-file \
  -Dfile=lib/resvg-jni-0.1.4.jar \
  -DgroupId=me.aloic \
  -DartifactId=resvg-jni \
  -Dversion=0.1.4 \
  -Dpackaging=jar
Both commands must succeed (look for BUILD SUCCESS) before proceeding. Run them from the root of the cloned repository.
3

Configure application.yaml

Copy the provided template to create your live configuration file:
cp src/main/resources/application.yaml.template \
   src/main/resources/application.yaml
Open src/main/resources/application.yaml in your editor and fill in all the required fields. The most important ones are:
KeyWhat to set
spring.datasource.urlJDBC URL, e.g. jdbc:mysql://localhost:3306/lazybot_schema
spring.datasource.usernameYour MySQL username
spring.datasource.passwordYour MySQL password
discord.bot.tokenDiscord bot token from the Developer Portal
discord.bot.keyDiscord bot public key
discord.bot.idDiscord application ID
discord.bot.secretDiscord OAuth2 client secret
lazybot.client_idosu! OAuth application client ID
lazybot.client_secretosu! OAuth application client secret
lazybot.oauth.redirect-uriYour publicly reachable OAuth callback URL
lazybot.prefixCommand prefix (default: /)
lazybot.global.discord.enabledSet to true to enable the Discord bot
lazybot.global.tencent.enabledSet to true to enable the QQ bot
To obtain osu! credentials, visit osu.ppy.sh → Settings → OAuth and create a new application. Set the Callback URL to the value you will put in lazybot.oauth.redirect-uri.
Two optional environment variables control where Lazybot writes its runtime files:
  • LAZYBOT_DIR — directory for Lazybot’s cache files (avatar images, rendered panels, etc.). If unset, the OS temporary directory is used.
  • RESVG_DIR — directory where the Resvg JNI library unpacks its native process binary. If unset, the OS temporary directory is used.
Setting these explicitly (e.g. in the lazybot.service systemd unit) gives you predictable paths and avoids cluttering /tmp.
4

Initialize the Database

Lazybot requires a pre-existing MySQL schema with the correct table structure. Create the database and run the provided SQL script:
# Create the schema (adjust credentials as needed)
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS lazybot_schema CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# Run the table-creation script
mysql -u root -p lazybot_schema < script.sql
Make sure spring.datasource.url in your application.yaml points to the same schema name used above (lazybot_schema by default).
Lazybot uses MyBatis-Plus for ORM. The schema must be initialised manually via script.sql — there is no automatic migration or schema generation on first boot.
5

Build and Run Lazybot

Build the fat JAR with the Maven wrapper (skip tests on first run):
./mvnw clean package -DskipTests
A successful build produces a JAR at target/lazybot-<version>.jar. Launch it with the required JVM flags:
java --enable-preview \
     --enable-native-access=ALL-UNNAMED \
     -jar target/lazybot-*.jar
Both --enable-preview (Java 21 preview features) and --enable-native-access=ALL-UNNAMED (Resvg JNI native library) are required — the bot will not start correctly without them.You should see Spring Boot’s startup banner followed by log lines confirming that the Discord gateway and/or the Shiro WebSocket server have connected.

​
Running as a systemd Service (Linux)

For production deployments, a ready-made systemd unit file is provided at scripts/lazybot.service. Copy it to /etc/systemd/system/, edit the paths to match your setup, then:
sudo systemctl daemon-reload
sudo systemctl enable lazybot
sudo systemctl start lazybot
The service runs under a dedicated lazybot user, restarts automatically on failure, and logs to journald.

​
Test Your Bot

Once Lazybot is running, verify everything works end-to-end:
  1. Check the help page — in Discord, type /help in any channel the bot can read. On QQ, send /help in the group where your OneBot client is active.
  2. Link your osu! account — before you can query scores, bind your osu! username to your Discord or QQ ID: 
    /link <your-osu-username>
    Lazybot will send an osu! OAuth authorization link. Complete the flow in your browser and your account will be bound.
  3. Fetch your best play — once linked, try: 
    /bp 1
    You should receive a rendered score panel image of your #1 best performance.

​
Next Steps

Configuration Reference

Explore every application.yaml setting in detail — rate limiting, async thread pools, avatar cache TTL, and more.

Score Commands

Full documentation for /bp, /score, /recent, /nochoke, /bpvs, /filter, and all other performance commands.

Build docs developers (and LLMs) love

Get started for freeTalk to us