Skip to content

Run with Docker

The Docker image includes Java and the right system libraries, so you don't need to install Java or check glibc. It runs on x86 (amd64) and ARM64 machines, including a Raspberry Pi 4 or 5 with a 64-bit OS.

The image is ghcr.io/arif-banai/musicbot. Tags:

  • latest: the newest build of the master branch, which can be ahead of the last release.
  • A version, such as 0.8.0: that release only. Pin a version for anything you rely on, and update on purpose.

You still need a bot token and your user ID.

Pick a folder

The container keeps config.txt, playlists and settings in a folder on your machine, mounted at /musicbot. Create one:

mkdir -p ~/jmusicbot

The bot runs as user ID 10001 inside the container, so that user needs to be able to write to the folder. On Linux:

sudo chown 10001:10001 ~/jmusicbot

Or run the container as yourself by adding --user "$(id -u):$(id -g)" to docker run (or a user: line in Compose).

First start: answer the questions

The first time, there's no config.txt, so the bot asks for the token and your user ID, just like the first run without Docker. That needs an interactive terminal, so start it once with -it:

docker run --rm -it \
  --name jmusicbot \
  -v ~/jmusicbot:/musicbot \
  ghcr.io/arif-banai/musicbot:latest

Paste the token and your ID when asked. The bot writes ~/jmusicbot/config.txt and connects. Press Ctrl+C to stop it once you've seen it start.

Started it in the background first?

Without -it, the bot can't ask its questions. It stops with No token provided! Exiting. and doesn't create config.txt. Either run the command above once, or create config.txt in the folder yourself with your token and owner ID (see config.txt).

Keep it running with Compose

Save this as docker-compose.yml, changing the folder path:

services:
  jmusicbot:
    image: ghcr.io/arif-banai/musicbot:0.8.0
    container_name: jmusicbot
    volumes:
      - ~/jmusicbot:/musicbot
    restart: unless-stopped
    # environment:
    #   - JAVA_OPTS=-Xms256m -Xmx512m -XX:+UseZGC -XX:+AlwaysPreTouch

Then start it in the background and follow the log:

docker compose up -d
docker compose logs -f

restart: unless-stopped brings the bot back after a crash or a reboot.

Moving from the jar

If you already run the jar, stop it and mount its folder (the one with config.txt and Playlists/) at /musicbot. The container uses your existing settings and playlists:

cd /path/to/your/jmusicbot
docker run --rm -it --user "$(id -u):$(id -g)" -v "$(pwd):/musicbot" ghcr.io/arif-banai/musicbot:latest

--user runs the container as you, so it can write to your existing files. Without it the container runs as user 10001, can't write to the folder, and stops with "Another instance of JMusicBot is already running". Alternatively, give the folder to user 10001 with sudo chown -R 10001:10001 /path/to/your/jmusicbot.

Updating

Change the version tag in docker-compose.yml, then:

docker compose pull
docker compose up -d

Your folder keeps everything, so updating doesn't touch your settings.

Memory and Java options

The image starts Java with ZGC and AlwaysPreTouch for smooth audio. Set JAVA_OPTS to add a memory limit or change the flags; see Performance tuning.

The image doesn't include yt-dlp. To use the yt-dlp library, mount a yt-dlp binary into the container and set ytdlp.path to its path inside the container.

Next: Invite the bot.