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](https://github.com/air-verse/air) for live reload, [Just](https://github.com/casey/just) for shortcuts, and a [Lavalink](https://github.com/lavalink-devs/Lavalink) server if you want music.

## 1. Create the Discord application

1. Open the [Discord developer portal](https://discord.com/developers/applications) 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 |
   | Use External Emojis | embeds that use custom emojis |
   | 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:

```bash
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 stored in the database. See [Beta features](beta-features.md).

## 3. Set up the database

Start PostgreSQL with Compose:

```bash
docker compose up -d db
```

Then load the schema:

```bash
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 the schema of every table the bot uses. Read [Database](database.md) before changing a table.

## 4. Run

```bash
go run .
```

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

With live reload:

```bash
air
```

With Just (`Justfile`):

```bash
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).
- `/config toggletwitch` and `/config addstreamer` for Twitch alerts.

`/security settings`, `/tickets settings`, `/slvl status` and `/config view` show what is set.

The [Features](features.md) page explains each module, and the [Command reference](commands.md) 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](deployment.md).
- Changing or adding things: [Development guide](development.md).