# Host your own bot

This guide takes you from a clean server to your own Velox running under your own Discord application. It uses Docker Compose, which is the simplest way. For the Discord side in more detail, see [Getting started](getting-started.md). For a short run on your own machine while developing, see that page too.

You will run:

- **The bot** (this repository). It needs PostgreSQL.
- **PostgreSQL**, started by the same Compose file.
- Optionally **Lavalink**, if you want music.

The web dashboard lives in two other repositories (`velox-dashboard-api` and `velox-dashboard-web`) and is optional. See [What you get without the dashboard](#what-you-get-without-the-dashboard).

## Before you start

You need:

- A Linux server (or any machine that is always on) with [Docker and Docker Compose](https://docs.docker.com/engine/install/). The bot itself is a small static Go binary and needs little. Lavalink is a Java program and needs noticeably more memory, so size the server for it if you want music.
- A Discord account that can create an application.
- A way to reach the server over SSH, and a firewall that does not expose PostgreSQL.

You do not need a domain name or an open port. The bot only makes outgoing connections to Discord (and to Lavalink and Twitch if you use them).

## 1. Create your Discord application

Follow [step 1 of Getting started](getting-started.md#1-create-the-discord-application). You end up with:

- an **application ID** (`APP_ID`),
- a **bot token** (`BOT_TOKEN`), which is a password: never commit it or paste it anywhere public,
- the **Server Members** and **Message Content** privileged intents switched on.

### The invite link

Invite your bot with this link, replacing `YOUR_APP_ID`:

```
https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot%20applications.commands&permissions=1460577627318
```

The number is the set of permissions the bot uses across all its modules: View Channels, Send Messages, Embed Links, Attach Files, Read Message History, Use External Emojis, Manage Messages, Manage Roles, Manage Channels, Manage Server, Kick Members, Ban Members, Moderate Members, View Audit Log, Create Private Threads, Send Messages in Threads, Manage Threads, Connect, Speak and Move Members. If you never use a module you can leave its permissions out. The [permission table](getting-started.md#1-create-the-discord-application) says which module needs which.

After inviting, drag the bot's role **above** the roles it should manage and the members it should moderate. Discord does not let a bot change anyone whose highest role is above its own.

## 2. Get the code

```bash
git clone <this repository> velox-bot
cd velox-bot
```

## 3. Configure

Create a file called `.env` next to `docker-compose.yml`:

```bash
BOT_TOKEN=paste-your-bot-token
APP_ID=paste-your-application-id
# Register commands in one server (appear at once). Leave empty to register
# them globally, which Discord can take up to an hour to show.
GUILD_ID=paste-a-server-id
# Used for Twitch live alerts. Required to start, even if you never use them
# (any value works then). See "Twitch" below.
TWITCH_CLIENT_ID=unused
```

You do not set `DB_HOST` here: the Compose file points the bot at its own database. **Change the database password**, though. In `docker-compose.yml`, replace `velox_pwd` in two places (the `db` service's `POSTGRES_PASSWORD` and the default `DB_HOST` of the `bot` service), or set `DB_HOST` in `.env` yourself:

```bash
DB_HOST=postgres://velox:A-LONG-RANDOM-PASSWORD@db:5432/velox?sslmode=disable
```

and set the same password for `POSTGRES_PASSWORD`. Then remove the `ports: - "5432:5432"` lines of the `db` service so the database is only reachable from the bot.

`.env` holds secrets. Keep it out of version control (it is already in `.gitignore`) and readable only by you: `chmod 600 .env`.

## 4. Start the database and load the schema

```bash
docker compose up -d db
docker compose exec -T db psql -U velox -d velox < schema.sql
```

The schema file can be run again at any time, it only creates what is missing.

## 5. Start the bot

```bash
docker compose up -d --build bot
docker compose logs -f bot
```

You should see the bot connect and no errors. In your server, type `/ping`. If the commands do not appear, see [Troubleshooting](troubleshooting.md#slash-commands-do-not-appear).

The Compose file restarts the bot automatically (`restart: unless-stopped`), including after a reboot of the server, as long as Docker starts at boot (`sudo systemctl enable docker`).

## 6. Turn modules on

Nothing is on by default. Follow [Turn modules on](getting-started.md#5-turn-modules-on).

## Music (optional)

Music needs a [Lavalink](https://github.com/lavalink-devs/Lavalink) server. Add it to `docker-compose.yml`:

```yaml
  lavalink:
    image: ghcr.io/lavalink-devs/lavalink:4
    container_name: velox-lavalink
    restart: unless-stopped
    environment:
      LAVALINK_SERVER_PASSWORD: ${LAVALINK_PASSWORD}
    # Not published: only the bot, on the same Compose network, needs it.
```

and put the password in `.env`:

```bash
LAVALINK_PASSWORD=another-long-random-password
```

The Compose file already defaults `LAVALINK_HOST` to `ws://lavalink:2333` for the bot, so the two find each other. Restart with `docker compose up -d`.

Two things to know:

- Lavalink 4 does not play from every source out of the box. Playing from YouTube needs a source plugin configured in Lavalink. See Lavalink's own documentation for what is current, since it changes.
- Members need a role named exactly **DJ** to use the music commands.

## Twitch alerts (optional)

Twitch live alerts check streamers every 30 seconds, using Twitch's web GraphQL endpoint with the client ID you set in `TWITCH_CLIENT_ID`. That is not Twitch's official API and Twitch can change or block it without notice. If you do not use alerts, leave the value as is and never set a notification channel.

## Keeping it running

**Updates.**

```bash
git pull
docker compose up -d --build bot
```

Read the release notes first. Releases that add tables need `schema.sql` run again (it only creates what is missing, and is safe to repeat) before the bot restarts, and a release that changes an existing table says so in its notes. Slash commands update themselves when the bot starts.

**Backups.** Everything the bot stores is in PostgreSQL:

```bash
docker compose exec -T db pg_dump -U velox velox > velox-backup-$(date +%F).sql
```

Run it on a schedule and keep copies off the server. To restore into an empty database, load the file with `psql`.

**Logs.** `docker compose logs -f bot`. Docker keeps logs without limit by default. Set a log size limit for the `bot` service (`logging` options in Compose) if the server is small.

**Rotating the token.** If the bot token ever leaks, reset it in the developer portal at once, put the new one in `.env` and run `docker compose up -d bot`.

## Growing past 100 servers

Discord requires you to **verify** your application once the bot is in 100 servers, and to be approved for the privileged intents (Server Members, Message Content). Plan for that if you intend to run a public bot. For a bot in a few servers you manage yourself, nothing is needed.

## What you get without the dashboard

The bot works on its own and every command in the [Command reference](commands.md) does. What needs the dashboard (the `velox-dashboard-api` and `velox-dashboard-web` repositories, which share this database):

- Security thresholds, Join Gate filters and heat settings. Without the dashboard the bot uses the defaults from the schema.
- Beta access: choosing the beta server and role, and servers opting in. Without the dashboard there is no way to set a role, so beta features stay off.
- The web view of the music queue and ticket panel, and the changelog.

If you do run the dashboard, it and the bot must use the **same PostgreSQL database**, and the API runs the migrations. Its own README explains its setup. When both are deployed, [deploy the API first](deployment.md#running-next-to-the-dashboard).

## Making it your own

- Change the bot's name and avatar in the developer portal.
- `/help` is hand-written text in `internal/commands/help/help.go`. Its author link points at the original project, so change it to your own repository.
- The name "Velox" in this code is just a name. You may rename it, and under the license you must keep the copyright notices (`LICENSE`, `NOTICE`) and say what you changed. Please do not present your fork as the original project.

## Something went wrong

[Troubleshooting](troubleshooting.md) covers the usual problems: the bot not starting, commands not appearing, permissions, and music.