Local setup

By the end of this page the bot is running on your machine, logged in to your Discord server, with a migrated database behind it.

What you need

Requirement	Detail
Node	Version 24. The bot declares >=24.21.0 and .nvmrc holds 24.21.0. Install it from nodejs.org or with a version manager such as nvm.
Bun	Installs dependencies and runs the scripts (curl -fsSL https://bun.sh/install | bash). bun run does not load .env for the dev server or the migration script, so the commands below pass --env-file to Bun.
Postgres database	A Neon database (a hosted Postgres service) with the vector extension (pgvector, which stores the numbers used for search by meaning). The tests and CI use Postgres 18.
Discord application	A bot in a test server. See Discord application. Use a test application: a second copy of the bot with the same token and server answers too.

Set it up

1. Clone the bot repository and install.

   git clone git@github.com:dogelabsvr/doge-discord-bot.git && cd doge-discord-bot && bun install

2. Create your env file.

   cp .env.example .env

   Never commit .env. The example file says where each value comes from. Keep values bare: no # comment after a value on the same line.

3. Fill in the four required values. Open .env in an editor and set DISCORD_TOKEN, DISCORD_GUILD_ID, DATABASE_URL_POOLED and DATABASE_URL. The bot refuses to start without them. Also set REMINDER_ALLOWLIST to your own Discord user id (see the warning under What a good start looks like). See Configuration for every variable.

   Create the database shows where to click. Neon gives two URLs for one database: the pooled one (host contains -pooler) is DATABASE_URL_POOLED, the direct one is DATABASE_URL. With a local Postgres both are the same URL.

4. Enable pgvector. In your database, for example in the Neon SQL Editor, run:

   CREATE EXTENSION IF NOT EXISTS vector;

   A migration (a script that creates the bot’s tables) runs this too, but only a database user allowed to create extensions can. On a local Postgres on macOS, run brew install pgvector first.

5. Apply the migrations.

   bun --env-file=.env run db:migrate

   The package scripts do not read .env themselves, so --env-file hands the file to Bun for this one command. It prints [migrate] complete on success. It reads DATABASE_URL, which must be the direct URL, and always connects with TLS (an encrypted connection). A local Postgres without TLS cannot use it: apply the migrations with psql instead, the way the tests do.

6. Start the bot in watch mode. Leave this terminal open: the bot runs in it.

   bun --env-file=.env run dev

   Watch mode restarts the bot when you save a file. Stop it with Ctrl+C.

What a good start looks like

The terminal shows [http] listening on :3000, then [bot] logged in as <bot tag> and [bot] registered N guild commands, then one line per feature saying enabled, disabled or off: needs .... Asking, summaries, ticket prompts, meeting transcripts and voice notes are off by default. Scripts and health lists every line. If the bot exits instead, see Troubleshooting.

Then, in Discord, type /whoami in any channel of your server. If the bot answers with your member profile (only you see it), the setup works. The bot also starts reading your server’s message history in the background. That is normal: see First start.

Reminders are on by default

With REMINDER_ALLOWLIST empty, reminders go to everyone in the server who has set a timezone and working hours, and every member who has not gets a one-time setup DM (up to 25 per tick). On a shared server, set the allowlist to your own Discord user id before the first start. It also limits scheduled summary and ticket prompt DMs if you turn those on.

Compile and run like production

bun run build
node --env-file=.env dist/index.js

build compiles to dist/ and rewrites the @/ import aliases. Production runs node dist/index.js with Node, not Bun. bun run start runs the same file but does not load .env.

Run the tests

Command	What it does
bun run test	Unit tests.
bun run typecheck	Type check with tsc --noEmit.
bun run verify	Typecheck and unit tests together.
bun run test:integration	Integration tests against a real database.

The unit tests need no database. Integration tests need TEST_DATABASE_URL, the direct URL of a throwaway database with pgvector (on a Neon branch run CREATE EXTENSION vector;; on a local Postgres on macOS run brew install pgvector first). Use a separate Neon branch, never your real data. The tests do not read .env, so put the variable in the command’s environment: TEST_DATABASE_URL=<url> bun run test:integration. Without it they stop with TEST_DATABASE_URL is required for integration tests. The integration files run one after another because they share the database.

They do not create the tables. Apply the migrations to the test database first, the way CI does. This needs psql, the Postgres command line client:

for f in src/db/migrations/*.sql; do psql "$TEST_DATABASE_URL" -v ON_ERROR_STOP=1 -f "$f"; done

Next

• Discord application to create the bot and get its token.
• Configuration for every environment variable.