Self-Hosting

Self-Host DJMusicBot

Run your own private instance of DJMusicBot with full control over configuration, uptime, and credentials — all in a single Docker command.

Prerequisites

You will need the following before starting.

  • Docker & Docker Compose

    Install Docker Desktop (Windows/macOS) or Docker Engine + Compose plugin (Linux). Version 20.10+ recommended.

  • Git

    Used to clone the repository. Any recent version of Git will work.

  • Discord Bot Token

    A bot application created in the Discord Developer Portal with a valid bot token. See the guide below for step-by-step instructions.

  • Spotify API Credentials (optional)

    A Spotify Developer application Client ID and Client Secret. Required only if you want Spotify URL support. YouTube playback works without it.

Setup Steps

Run these commands in your terminal from your desired project directory.

  1. 1

    Clone the Repository

    Download the DJMusicBot source code to your machine.

    git clone https://github.com/mauriciomartinezc/dj-music-bot-discord cd dj-music-bot-discord
  2. 2

    Copy the Environment File

    The repository includes a template environment file. Copy it to create your local configuration file.

    cp .env.example .env

    On Windows (PowerShell), use:

    Copy-Item .env.example .env
  3. 3

    Edit Your .env File

    Open .env in a text editor and fill in your credentials. Never share or commit this file to version control.

    # Discord (required) DISCORD_TOKEN=your_discord_bot_token_here DISCORD_APP_ID=your_application_id_here DISCORD_PUBLIC_KEY=your_public_key_here # Spotify (optional — for Spotify URL support) SPOTIFY_CLIENT_ID=your_spotify_client_id_here SPOTIFY_CLIENT_SECRET=your_spotify_client_secret_here # Bot behavior (optional — defaults shown) DEFAULT_VOLUME=100 MAX_QUEUE_SIZE=500 LOG_LEVEL=info NODE_ENV=production
    Security: The .env file is listed in .gitignore. Never commit it to a public repository.
  4. 4

    Build & Start with Docker Compose

    This single command builds the Docker image and starts the bot in detached mode.

    docker compose up -d --build

    The bot will start and connect to Discord automatically. To check the logs in real time:

    docker compose logs -f bot
    Success: When you see [ready] Logged in as DJMusicBot in the logs, your bot is live and ready to use.

Getting Your Tokens

Step-by-step instructions for obtaining the credentials you need.

Discord Bot Token

  1. 1. Go to discord.com/developers/applications and log in.
  2. 2. Click New Application, give it a name, and click Create.
  3. 3. In the left sidebar, click Bot.
  4. 4. Click Reset Token and confirm. Copy the token immediately.
  5. 5. Scroll down and enable Message Content Intent under Privileged Gateway Intents.
  6. 6. Paste the token as the value of DISCORD_TOKEN in your .env file.

Spotify API Credentials Optional

  1. 1. Go to developer.spotify.com/dashboard and log in with your Spotify account.
  2. 2. Click Create App. Fill in the name and description. Set redirect URI to http://localhost.
  3. 3. Open your app and go to Settings.
  4. 4. Copy the Client ID and Client Secret into your .env file.

Common Issues

Frequently encountered problems and how to resolve them.

Bot starts but does not appear online in Discord

Check your DISCORD_TOKEN value in .env. A common mistake is including extra whitespace or copying an expired token. Regenerate the token in the Developer Portal and update .env, then restart with docker compose restart bot.

docker-compose command not found

Newer versions of Docker ship Compose as a plugin, not a standalone binary. Modern Docker ships Compose as a plugin: use docker compose (no hyphen). If that also fails, install Docker Desktop or the Docker Compose plugin for your OS.

Spotify tracks fail with "could not resolve track"

Verify that SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET are correct and that your Spotify Developer App is not in development mode with restricted users. Also confirm your server can reach api.spotify.com outbound.

No audio / voice channel errors

The bot requires FFmpeg to encode audio. The Docker image bundles FFmpeg automatically. If you are running the bot outside Docker, install FFmpeg and ensure it is on your system PATH.

Updating to a new version

Pull the latest changes and rebuild the image:

git pull docker compose up -d --build

How to stop or remove the bot

To stop the bot: docker compose down.
To stop and remove all data volumes: docker compose down -v.