> ## Documentation Index
> Fetch the complete documentation index at: https://docs.discord-bot.xxczaki.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-Hosted

> Deploy your own instance using Docker or the Helm chart

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

<Warning>
  Please read the [Legal Disclaimer](https://github.com/xxczaki/discord-bot/blob/main/legal.md) in the repository before using this software.
</Warning>

**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](https://discord.com/developers/applications)
* **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](https://kubernetes.io/docs/concepts/configuration/secret/) 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](https://docs.docker.com/compose/how-tos/use-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.

```bash theme={null}
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](https://artifacthub.io/packages/helm/xxczaki/discord-bot) and the source is on [GitHub](https://github.com/xxczaki/charts/tree/main/charts/discord-bot). See `values.yaml` for the full list of configurable options. For Argo CD users, see [this example Application manifest](https://github.com/xxczaki/homelab/blob/main/apps/discord-bot/application.yaml).

## Option 2: Docker

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

```bash theme={null}
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.

<Tabs>
  <Tab title="Docker Hub">
    ```
    docker pull xxczaki/discord-bot
    ```
  </Tab>

  <Tab title="GitHub Container Registry">
    ```
    docker pull ghcr.io/xxczaki/discord-bot
    ```
  </Tab>
</Tabs>

## Option 3: Railway

<Warning>
  Ensure your usage complies with [Railway's Terms of Service](https://railway.com/legal/terms) and [Fair Use Policy](https://railway.com/legal/fair-use). Enabling YouTube support may violate both Railway's and YouTube's terms. You are responsible for any content streamed through your deployment.
</Warning>

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

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/tgifQE?referralCode=4Ee-1n)

## 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.