velox-bot/docs/self-hosting.md

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

Before you start

You need:

• A Linux server (or any machine that is always on) with Docker and Docker Compose. 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. 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 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

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

3. Configure

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

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:

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

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

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.

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.

Music (optional)

Music needs a Lavalink server. Add it to docker-compose.yml:

  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:

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.

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:

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

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 covers the usual problems: the bot not starting, commands not appearing, permissions, and music.