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.

This guide walks you through the complete process of getting a Lazybot instance running from source: cloning the repository, installing the local Maven libraries, filling in your application.yaml, initialising the database, and building the self-contained JAR. By the end you will have a working lazybot-1.2.0.jar ready to run directly or deploy under systemd.

​
Step-by-Step Setup

1

Clone the Repository

Clone the project to your local machine or server:
git clone https://github.com/Apeuriox/lazybot-renewal.git
cd lazybot-renewal
2

Install Local Maven Libraries

Lazybot depends on two JNI libraries that are not available on Maven Central. Both JARs are bundled in the lib/ directory. Install them into your local Maven repository before attempting a build.rosu-jni — osu! difficulty and performance-point calculation:
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 — fast SVG-to-PNG rendering:
mvn install:install-file \
  -Dfile=lib/resvg-jni-0.1.4.jar \
  -DgroupId=me.aloic \
  -DartifactId=resvg-jni \
  -Dversion=0.1.4 \
  -Dpackaging=jar
3

Configure application.yaml

Copy the provided template and edit the required values:
cp src/main/resources/application.yaml.template \
   src/main/resources/application.yaml
Open src/main/resources/application.yaml in your editor. At minimum, fill in the sections below.Database connection — replace the placeholder URL, username, and password:
spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/lazybot_schema
    username: root
    password: your_database_password
Discord bot credentials — required if lazybot.global.discord.enabled: true:
discord:
  bot:
    key: your_discord_bot_key
    id: your_discord_bot_id
    secret: your_discord_bot_secret
    token: your_discord_bot_token
osu! API credentials — obtained from your OAuth application at osu.ppy.sh/home/account/edit:
lazybot:
  client_id: your_osu_client_id
  client_secret: your_osu_client_secret
  scopes: friends.read identify public
  oauth:
    redirect-uri: https://your-domain.example/oauth/osu/callback
    scopes: identify public
Platform toggles — enable whichever platforms you need:
lazybot:
  global:
    discord:
      enabled: true   # set to true to activate Discord
    tencent:
      enabled: true   # set to false to disable QQ/Tencent
application.yaml contains secrets (database passwords, bot tokens, and API credentials). Never commit this file to version control. It is listed in .gitignore by default — do not override that.
4

Initialise the Database

Create the lazybot_schema database and run the bundled SQL script to build all required tables:
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS lazybot_schema \
  CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

mysql -u root -p lazybot_schema < script.sql
The schema name must match the value in spring.datasource.url inside your application.yaml.
5

Build the JAR

Use the Maven wrapper to compile and package Lazybot into a single executable JAR. The --enable-preview flag is applied automatically by the build configuration in pom.xml.
./mvnw clean package -DskipTests
On success, the artifact is written to:
target/lazybot-1.2.0.jar
6

Run Lazybot

Launch the JAR with the required JVM flags:
java --enable-preview \
     --enable-native-access=ALL-UNNAMED \
     -jar target/lazybot-1.2.0.jar
Both --enable-preview and --enable-native-access=ALL-UNNAMED are mandatory. Omitting either flag will cause startup failures.

​
Environment Variables

Lazybot reads three optional environment variables at startup. Setting them explicitly is recommended for production deployments so that cache files land in predictable, persistent locations rather than system temp directories.
VariablePurposeDefault
LAZYBOT_DIRWorking directory for Lazybot cache files (avatars, map backgrounds, extracted static assets)OS temporary directory
RESVG_DIRDirectory where the resvg render-process writes its native library cacheOS temporary directory
ROSU_LIB_PATHDirectory containing the Rosu native library (.so on Linux, .dll on Windows)—

​
Full Run Command with Environment Variables

export LAZYBOT_DIR=/home/lazybot/work-dir
export RESVG_DIR=/home/lazybot/resvg-cache
export ROSU_LIB_PATH=/home/lazybot/rosu

java --enable-preview \
     --enable-native-access=ALL-UNNAMED \
     -jar target/lazybot-1.2.0.jar

​
Local Testing

Set lazybot.test.enabled: true in application.yaml to enable local testing mode. You can also set lazybot.test.path to a local output directory and lazybot.test.identity to a test user identity string, which lets you exercise rendering and command logic without a live Discord or QQ connection.

​
What Happens at Startup

When Lazybot starts, InitializeConfig (an ApplicationRunner) performs three tasks in order:
  1. ResourceMonitor.initResources() — resolves LAZYBOT_DIR, creates the required subdirectory structure (osuFiles/, static/, static/badge/, static/assets/, etc.), and extracts bundled static assets from inside the JAR into that working directory.
  2. tokenMonitor.refreshClientToken() — fetches a fresh osu! client credentials token from the osu! API using your configured client_id and client_secret.
  3. tokenMonitor.refreshPPPlusClientToken() — fetches a token for the pp+ scoring endpoint using the lazybot.plus.* credentials.
If LAZYBOT_DIR is not set, a temporary directory is created automatically and a warning is logged. The application will still start, but cache files will be lost on reboot.

Build docs developers (and LLMs) love

Get started for freeTalk to us