Evidence BotInstallation & Setup

Evidence Bot Installation & Setup

Install the ZCraft Studios Discord Evidence Bot. Configure Discord permissions, forum tags, environment variables, hosting and first-run checks.

Evidence Bot Installation & Setup

Requirements

  • Node.js 22.13 or newer, and npm. SQLite migration uses Node's built-in SQLite reader, so no extra runtime dependency is needed.
  • A Discord application with a bot token
  • A Discord server with a Forum channel for case posts
  • Permission to install and configure the bot in that server
  • A host with a persistent, writable directory and internet access to Discord
  • Optional: a MySQL/MariaDB database used by LiteBans or AdvancedBan, with a SELECT-only user for the bot

The bot is configured for one server and one evidence forum per running installation, with one bot instance per installation. The base package has no website, dashboard, or HTTP listener; those come from the optional addons.

Discord setup

Create the application

  1. Open the Discord Developer Portal and create or select an application.
  2. In Bot settings, get the bot token. Save it privately for TOKEN.
  3. Enable Message Content Intent.

Install the bot

Use an install link with the bot and applications.commands scopes, and grant the permissions below. Give members permission to use application commands.

Create channels and staff roles

Create a Forum channel for evidence cases. Optional channels: appeal intake, activity log, and review reminders. Enable Discord Developer Mode to copy IDs: the server ID is GUILD_ID and the forum's channel ID is FORUM_CHANNEL_ID.

Create forum tags

Create the seven status tags listed below in the evidence forum.

Appeal posts can contain email addresses, punishment details, and submitted evidence. Keep the appeal forum private and set visibility for your intended audience only.

Required bot permissions

PermissionPurpose
View ChannelAccess the forum and configured text channels.
Send MessagesCreate forum posts and send logs or reminders.
Send Messages in ThreadsPost follow-ups and appeal decisions.
Embed LinksSend structured case embeds.
Read Message HistoryRead starter messages and recover forum records.
Create Public ThreadsAllow thread creation where applicable.
Manage ThreadsRename, tag, archive, and unarchive posts.
Attach FilesDeliver exports, timelines, and queue downloads.

Check channel overrides as well as the bot's server role. Thread visibility follows the forum's permissions.

Forum tags

Create tags named Banned, Muted, Kicked, Pending, Suspicious, Appeal, and Resolved. These names are sufficient.

Internal statusDisplay labelTag nameOptional env override
bannedBannedBannedTAG_ID_BANNED
mutedMutedMutedTAG_ID_MUTED
kickedKickedKickedTAG_ID_KICKED
pendingPending ReviewPendingTAG_ID_PENDING
suspiciousSuspiciousSuspiciousTAG_ID_SUSPICIOUS
appealAppealAppealTAG_ID_APPEAL
resolvedResolvedResolvedTAG_ID_RESOLVED

The TAG_ID_* overrides still work if you use custom tag names. Status changes preserve unrelated tags up to Discord's five-tag limit. A forum that requires tags will reject new cases if the status tag is missing.

Install and run the bot

Run all commands from the extracted bot directory (where package.json is).

Install dependencies

node --version
npm ci

Use Node.js 22.13 or newer.

Create the environment file

cp .env.example .env

Edit .env

At minimum, set the required values:

TOKEN=your_bot_token
GUILD_ID=your_server_id
FORUM_CHANNEL_ID=your_evidence_forum_id
STAFF_ROLE_IDS=your_staff_role_id,your_admin_role_id

.env.example lists every normal setting. Channel and role settings take IDs, not names or mentions. Boolean settings accept true or false.

Start the bot

npm start

Startup logs in, then registers the 17 core guild slash commands plus any installed addon commands automatically, before starting background services. CLIENT_ID is no longer needed: the application ID is detected from the logged-in bot.

Registration clears this application's global commands and its commands in every server it currently belongs to, then registers the current core and configured addon commands only in GUILD_ID — removing older commands and any global/guild duplicates. If you run independent bots for different servers, use a separate Discord application per installation. A registration failure stops startup; npm run deploy is still available for standalone registration and exits with a nonzero code on failure.

While starting, the console prints its current step (Discord connection, forum validation, command refresh, addons, background services), elapsed time, and a progress line every 15 seconds while a step is still running. A Discord command rate limit prints its estimated wait. Forum recovery and MySQL polling run in the background and don't hold up the bot becoming ready.

Configure environment variables

Restart the bot after changing any setting. Invalid required settings fail startup with a configuration error.

VariableRequired?Description
TOKENYesDiscord bot token. Keep private.
GUILD_IDYesDiscord server ID. Commands and intake are restricted to this server.
FORUM_CHANNEL_IDYesEvidence Forum channel ID in that server.
STAFF_ROLE_IDSRecommendedComma-separated staff role IDs. Administrators always have access. When blank, only administrators can use staff commands.

LiteBans and AdvancedBan connection settings are listed under Punishment imports.

If STAFF_ROLE_IDS is blank, staff commands are limited to administrators. Add your moderator role IDs so non-admin staff can use them.

Keep .env private and never publish a real bot token.

Keep the bot running

Press Ctrl+C to stop a foreground instance, and stop your process manager as well when migrating. Closing a foreground terminal ends the session unless your host manages the process. Use a host or service manager that supports long-running Node.js processes:

  • Working directory: the folder containing package.json and .env
  • Install command: npm ci
  • Start command: npm start
  • Persistent storage: keep the data/ directory and configuration across restarts and redeploys

There is no port to expose for the base bot. Run one instance per installation and never share one data store between multiple copies. A local instance lock prevents concurrent startup and protects migration writes, but it does not coordinate separate hosts.

Verify the installation

  1. Confirm the 17 core slash commands registered to the intended server.
  2. Run /evidence as a staff member with a short test report and an attachment.
  3. Confirm the forum post shows the case ID, embed, and expected status tag.
  4. Assign the case, add a note with /followup, then close and reopen it.
  5. Find the case with /searchcases and download it with /caseexport.
  6. If configured, submit a test appeal from an allowlisted webhook and confirm it is imported.
  7. If you enabled LiteBans or AdvancedBan, issue a test punishment and confirm a case appears once, including after a restart.
  8. Restart the bot and confirm data/cases.json still holds the case.