Discord application setup#

Create one Discord application for each VTune instance. Keep it private and allow only the servers you intend to operate.

Create the application#

In the Discord Developer Portal, create an application and add a bot. Record the application/client ID, generate an OAuth client secret, and create the bot token. Store credentials only in your deployment secret store or .env; never commit them.

OAuth redirect#

Add this exact redirect URI, replacing the hostname with your public VTune domain:

https://music.example.com/auth/discord/callback

The scheme and host must match PUBLIC_BASE_URL. VTune uses the identify OAuth scope for dashboard sign-in.

Gateway and permissions#

Enable only the Guilds and GuildVoiceStates gateway intents. After setting the Discord values in .env and pulling the pinned image, generate the current invite URL from the published container:

docker compose -f compose.release.yaml run --rm --no-deps vtune \
  node dist/scripts/invite-url.js

Open the printed URL and add the bot only to a server listed in ALLOWED_GUILD_IDS. The bot needs permission to view and connect to the selected voice channel, speak, send messages, and use application commands. Do not grant Administrator.

Register commands immediately in every allowed server:

docker compose -f compose.release.yaml run --rm --no-deps vtune \
  node dist/scripts/register-commands.js allowed

This mode also clears any old global registrations so duplicate commands do not linger. Rerun it after an upgrade that changes the command set. Global registration is available to advanced operators by replacing allowed with global, but propagation can take longer and must not be used to bypass the server allowlist.

Restrict servers#

Set ALLOWED_GUILD_IDS to an explicit comma-separated allowlist. VTune rejects and leaves every other guild. Use DISCORD_DEV_GUILD_ID only when registering development commands to a test server.