velox-bot/docs/getting-started.md

Getting started

This page takes you from nothing to a bot running on your machine.

Requirements

• Go: the version in go.mod (the Dockerfile builds with the same one).
• PostgreSQL 16 or newer: the included docker-compose.yml starts one for you.
• A Discord application with a bot user (see below).
• Optional: Air for live reload, Just for shortcuts, and a Lavalink server if you want music.

1. Create the Discord application

1. Open the Discord developer portal and create an application. Copy its Application ID: this is APP_ID.

2. Under Bot, create the bot user and copy its token: this is BOT_TOKEN. Keep it secret.

3. Under Bot, switch on these privileged gateway intents: Server Members Intent (welcome messages, security) and Message Content Intent (leveling and spam detection). The bot also uses the non-privileged Guilds, Guild Moderation (bans and the audit log), Guild Messages, Guild Voice States and Direct Messages intents. You do not need to enable those by hand.

4. Invite the bot with the bot and applications.commands scopes. It needs these permissions, depending on which modules you use:

   Permission	Used by
   View Channels, Send Messages, Embed Links, Attach Files	everything that posts, ticket transcripts
   Read Message History, Manage Messages	moderation purge, spam heat
   Manage Roles	default role, level rewards, quarantine
   Manage Channels	lockdown, slowmode, meeting rooms, snapshot restore
   Manage Server	pausing invites during a raid
   Kick Members, Ban Members, Moderate Members	moderation commands, Join Gate, raid mode, anti-nuke
   View Audit Log	anti-nuke, unauthorised bot detection
   Create Private Threads, Send Messages in Threads, Manage Threads	tickets
   Connect, Speak, Move Members	music, meeting rooms

   The bot's role must sit above the roles it manages or protects against. Discord does not let a bot change members whose highest role is higher than its own.

2. Configure the environment

The bot reads environment variables, and loads a .env file from the working directory if there is one (internal/config/config.go).

Variable	Required	Meaning
BOT_TOKEN	yes	The bot token.
APP_ID	yes	The application ID.
GUILD_ID	no	If set, slash commands are registered in this server only, and appear within seconds. If empty they are registered globally, which Discord can take up to an hour to show. Use a test server while developing.
DB_HOST	yes	A pgx connection string, for example postgres://velox:velox_pwd@localhost:5432/velox?sslmode=disable.
TWITCH_CLIENT_ID	yes	A Twitch client ID, used to check who is live. The bot refuses to start without it, even if you never use Twitch alerts. Any non-empty value works if you do not use them.
LAVALINK_HOST	no	Lavalink address, for example ws://localhost:2333. Leave empty to run without music.
LAVALINK_PASSWORD	no	Lavalink password.

A minimal .env for local development:

BOT_TOKEN=your-bot-token
APP_ID=123456789012345678
GUILD_ID=123456789012345678
DB_HOST=postgres://velox:velox_pwd@localhost:5432/velox?sslmode=disable
TWITCH_CLIENT_ID=unused

.env is ignored by git. Never commit it.

Who the beta testers are is not an environment variable. It is set on the dashboard and stored in the database. See Beta features.

3. Set up the database

Start PostgreSQL with Compose:

docker compose up -d db

Then load the schema:

psql "postgres://velox:velox_pwd@localhost:5432/velox?sslmode=disable" -f schema.sql

schema.sql is written with CREATE TABLE IF NOT EXISTS, so running it again is safe. It is a mirror of the tables the bot uses. If you run the dashboard API as well, the API's migrations create and change these tables, and you do not need schema.sql at all. Read Database before changing a table.

4. Run

go run .

You should see the bot connect, and the slash commands appear in your test server. Type /ping.

With live reload:

air

With Just (Justfile):

just up      # start PostgreSQL
just start   # start PostgreSQL and run Air
just down    # stop PostgreSQL

5. Turn modules on

Nothing is on by default. In your server:

• /security toggle to enable Join Gate, raid mode, anti-nuke or heat.
• /tickets setup, then /tickets category add and /tickets panel.
• /slvl toggle for leveling.
• /config setlogchannel and /config enablelogging for logs.
• /music toggle for music (needs Lavalink).

The Features page explains each module, and the Command reference lists every option.

Optional: music with Lavalink

Music needs a running Lavalink server and LAVALINK_HOST / LAVALINK_PASSWORD. Without them the bot starts normally and music simply does not work. Members need a role named exactly DJ to use /play, /queue and /volume.

Next steps

• Running it for real: Deployment.
• Changing or adding things: Development guide.