Self-Hosted

The bot is fully open source and can be self-hosted on your own infrastructure. You’ll need a Discord bot token and a Redis instance.

Legal considerations

Please read the Legal Disclaimer in the repository before using this software.

YouTube: Enabling YouTube as a source may violate YouTube’s Terms of Service, which generally prohibit downloading content from their platform. You are solely responsible for compliance with all applicable laws and platform terms of service in your jurisdiction.

Prerequisites

Discord bot token from the Discord Developer Portal
Redis instance (for query cache, playback statistics, and queue recovery)
Docker or a Kubernetes cluster

Environment variables

Variable	Required	Description
`TOKEN`	Yes	Your Discord bot token
`REDIS_URL`	Yes	Redis connection string
`CLIENT_ID`	Yes	Discord application client ID
`OWNER_ROLE_ID`	Yes	Discord role ID for bot ownership (members with this role can use admin commands)
`PLAYLISTS_CHANNEL_ID`	Yes	Channel ID for playlist definitions
`BOT_DEBUG_CHANNEL_ID`	Yes	Channel ID for error and recovery messages
`DP_SPOTIFY_CLIENT_ID`	No	Spotify API client ID for enhanced search
`DP_SPOTIFY_CLIENT_SECRET`	No	Spotify API client secret
`ENABLE_YOUTUBE`	No	Set to `true` to enable YouTube as a source
`DISABLED_COMMANDS`	No	Comma-separated list of command names to disable
`OPENAI_API_KEY`	No	OpenAI API key for the `/prompt` command
`MISTRAL_API_KEY`	No	Mistral API key (alternative provider for `/prompt`)
`SENTRY_DSN`	No	Sentry DSN for error tracking

Secrets management

Sensitive variables like TOKEN, DP_SPOTIFY_CLIENT_SECRET, OPENAI_API_KEY, MISTRAL_API_KEY, and SENTRY_DSN should never be passed as plain text in command-line arguments or stored in version control.

Kubernetes – store secrets in Kubernetes Secrets and reference them in the Helm chart’s secrets.* values. The chart supports this natively for all sensitive variables.
Docker – avoid passing secrets via -e flags. Use Docker Compose secrets to mount them as files, or at minimum use --env-file with restrictive file permissions.

Option 1: Helm chart (recommended)

The Helm chart is the recommended deployment method for Kubernetes clusters. It includes a Redis dependency and handles configuration automatically.

helm repo add xxczaki https://xxczaki.github.io/charts
helm repo update
helm install discord-bot xxczaki/discord-bot \
  --set secrets.token.name=my-secret \
  --set secrets.token.key=DISCORD_TOKEN \
  --set env.clientId=your-client-id \
  --set env.ownerRoleId=your-role-id \
  --set env.playlistsChannelId=your-channel-id \
  --set env.botDebugChannelId=your-channel-id

The chart bundles a Redis dependency and handles its configuration automatically. The bot token is read from a Kubernetes Secret rather than passed as a plain value. The chart is available on Artifact Hub and the source is on GitHub. See values.yaml for the full list of configurable options. For Argo CD users, see this example Application manifest.

Option 2: Docker

Docker images are published to both Docker Hub and GitHub Container Registry.

docker run -d --env-file .env ghcr.io/xxczaki/discord-bot:latest

Images are multi-architecture (linux/amd64 and linux/arm64) and tagged with commit SHAs. The latest tag points to the most recent build.

Docker Hub
GitHub Container Registry

docker pull xxczaki/discord-bot

docker pull ghcr.io/xxczaki/discord-bot

Option 3: Railway

Ensure your usage complies with Railway’s Terms of Service and Fair Use Policy. Enabling YouTube support may violate both Railway’s and YouTube’s terms. You are responsible for any content streamed through your deployment.

For a one-click deployment, use the Railway template:

Limitations

The bot is designed for single-server use on a small scale (typically one voice channel at a time). It does not scale horizontally.

Getting Started

Hosting

Legal considerations

Prerequisites

Environment variables

Secrets management

Option 1: Helm chart (recommended)

Option 2: Docker

Option 3: Railway

Limitations

​Legal considerations

​Prerequisites

​Environment variables

​Secrets management

​Option 1: Helm chart (recommended)

​Option 2: Docker

​Option 3: Railway

​Limitations

Legal considerations

Prerequisites

Environment variables

Secrets management

Option 1: Helm chart (recommended)

Option 2: Docker

Option 3: Railway

Limitations