Self-hosting & development
Run your own instance
Section titled “Run your own instance”Requirements
Section titled “Requirements”- Node.js 22.12 or newer. This is required by the voice library (
@discordjs/voice0.19). - FFmpeg, for
/audio. Theffmpeg-staticnpm package normally provides it duringnpm 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.
Discord settings
Section titled “Discord settings”- 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.
Environment variables
Section titled “Environment variables”| 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 |
TOKEN=your_bot_tokenCLIENT_ID=your_client_idESV_API_KEY=your_esv_api_keyBIBLE_BRAIN_KEY=your_bible_brain_keyMONGO_URI=mongodb+srv://user:pass@host/scripturagit clone https://github.com/prinketaru/scriptura.gitcd scripturanpm installcp .env.example .env # fill in your valuesnpm run deploy # register slash commands with Discordnpm 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 |
Database
Section titled “Database”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 |
Updating
Section titled “Updating”After pulling a new version, run npm install (dependencies may have changed) and npm run deploy (to register new or changed commands).
Hosting
Section titled “Hosting”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.
Contributing
Section titled “Contributing”- Fork the repo and create a feature branch.
- Make your changes and run
npm run lint. - Test in Discord, including multiple translations and pagination (and voice, if you touched
/audio). - Open a pull request with a clear description.
Code style: tabs, single quotes, semicolons, JSDoc comments, ESLint. Contributions are licensed under GPL-3.0.
Project layout
Section titled “Project layout”- 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 |
Adding a command
Section titled “Adding a command”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.
Adding a translation
Section titled “Adding a translation”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 |

