Skip to content

Self-hosting & development

  • Node.js 22.12 or newer. This is required by the voice library (@discordjs/voice 0.19).
  • FFmpeg, for /audio. The ffmpeg-static npm package normally provides it during npm install. If your host blocks install scripts, install FFmpeg on the system instead.
  • A Discord application and bot token from the Discord Developer Portal
  • An ESV API key (required)
  • A Bible Brain API key, needed for every translation except ESV
  • A MongoDB database. Include the database name in the connection string.
  • The bot uses the Guild Voice States gateway intent. It isn’t privileged, so there’s nothing to turn on in the Developer Portal.
  • For /audio, the bot needs Connect and Speak. For /daily-channel, it needs View Channel, Send Messages and Embed Links. Consider adding these to your invite link’s permissions.
Variable Required Purpose
TOKEN Yes Discord bot token
CLIENT_ID Yes Discord application ID, used to register commands
ESV_API_KEY Yes ESV API key, used for both text and audio
BIBLE_BRAIN_KEY Yes, for non-ESV translations Bible Brain API key
MONGO_URI Yes MongoDB connection string
GUILD_ID No Clears leftover server-only commands in this server after registering global commands
.env
TOKEN=your_bot_token
CLIENT_ID=your_client_id
ESV_API_KEY=your_esv_api_key
BIBLE_BRAIN_KEY=your_bible_brain_key
MONGO_URI=mongodb+srv://user:pass@host/scriptura
Terminal window
git clone https://github.com/prinketaru/scriptura.git
cd scriptura
npm install
cp .env.example .env # fill in your values
npm run deploy # register slash commands with Discord
npm start # or: npm run dev for auto-reload
Script What it does
npm start Run the bot
npm run dev Run with auto-reload
npm run deploy Register slash commands with Discord
npm run lint / npm run lint:fix Check / fix code style

Scriptura uses two MongoDB collections:

Collection Stores
user_preferences Each user’s saved translation and display settings
guild_settings /daily-channel schedules, one document per server

After pulling a new version, run npm install (dependencies may have changed) and npm run deploy (to register new or changed commands).

Scriptura runs as a background worker and doesn’t need a web port. The included Procfile (worker: node deploy-commands.js && npm start) works on Heroku-style hosts and Dokku.

The repo also includes a GitHub Actions workflow that deploys to Dokku on every push to master. It needs the secrets DOKKU_HOST, DOKKU_APP and SSH_PRIVATE_KEY.

  1. Fork the repo and create a feature branch.
  2. Make your changes and run npm run lint.
  3. Test in Discord, including multiple translations and pagination (and voice, if you touched /audio).
  4. Open a pull request with a clear description.

Code style: tabs, single quotes, semicolons, JSDoc comments, ESLint. Contributions are licensed under GPL-3.0.

  • index.js Bot entry point (loads commands, handles interactions, daily status, starts the daily-post scheduler)
  • deploy-commands.js Registers slash commands with Discord
  • daily_verses.json Daily verse list
  • Directorycommands/
    • Directoryverses/ /verse
      • …
    • Directoryaudio/ /audio
      • …
    • Directoryutility/ /preferences, /daily-channel, /ping
      • …
  • Directoryhelpers/ Scripture API clients, translations, storage, embeds, voice sessions, scheduler, time zones
    • …

Some helpers worth knowing about:

File Purpose
helpers/ui.js Shared embed colors, error embeds, text truncation, BibleGateway links
helpers/voice_session.js One voice connection per server; plays audio and cleans up when playback ends or the channel empties
helpers/guild_settings.js Stores /daily-channel schedules in MongoDB
helpers/daily_verse_scheduler.js Checks every minute for servers whose daily verse is due and posts it
helpers/timezones.js Time zone validation, time parsing, next-post calculation, autocomplete

Create commands/<category>/<name>.js that exports data (a SlashCommandBuilder) and execute(interaction), then run npm run deploy. Commands load automatically.

A command can also export an optional autocomplete(interaction) handler. index.js routes autocomplete requests to it.

For replies, use the shared colors and error embeds in helpers/ui.js so they match the rest of the bot. /preferences uses Discord’s newer component layout (Components V2: containers, sections and buttons) if you need an example of that.

In helpers/translations.js, add the Bible Brain text fileset IDs to BIBLE_BRAIN_BIBLES and add a matching entry to translationChoices, then run npm run deploy. For reference, the existing fileset IDs are:

Code Fileset IDs
NKJV OT ENGNKJO_ET, NT ENGNKJN_ET
KJV OT ENGKJVO_ET, NT ENGKJVN_ET
NASB OT ENGNASO_ET, NT ENGNASN_ET
NLT OT ENGNLTO_ET, NT ENGNLTN_ET
ASV complete ENGASV