Evidence Bot Maintenance & Backups
Safely migrate Evidence Bot case data, recover forum records, back up an installation and update the bot without losing stored cases.
Evidence Bot Maintenance & Backups
Use this guide when moving Evidence Bot to another host, upgrading an installation or recovering stored case records. Stop the running bot before performing migrations or restoring data.
Migrating existing case data
Migration is explicit and does not run during startup. Stop the old and new bot processes first. Keep an untouched copy of your original data, including SQLite -wal and -shm files if present, and stop the old process cleanly so pending writes are checkpointed.
Supported sources
- JSON objects keyed by case ID, arrays of case records, or a
{ "cases": ... }wrapper. - Legacy SQLite databases with a
casestable and an optionalfollowUpstable.
Migration preserves case IDs, thread IDs, original timestamps, available follow-ups, and extra fields. Common snake_case names and status aliases are normalized. Missing guild and forum IDs can be supplied with --guild and --forum, or read from .env. Unknown statuses, malformed records, or corrupt data abort before anything is written. Missing historical evidence and status changes cannot be reconstructed, and the timeline labels recovered legacy entries accordingly.
npm run migrate -- --source /path/to/old/data/cases.json --dry-run
npm run migrate -- --source /path/to/old/data/cases.json
npm run migrate -- --source /path/to/old/data/cases.sqlite --dry-run
npm run migrate -- --source /path/to/old/data/cases.sqlite
npm run migrate -- --source data/cases.json --dry-run
npm run migrate -- --source data/cases.json
Optional arguments: --target /path/to/destination.json, --guild SERVER_ID, --forum FORUM_ID. The default destination is this installation's data/cases.json.
- Dry runs do not write any files.
- Applying a migration takes the bot's instance lock, backs up an existing destination to a timestamped
.bakfile, and writes through an atomic rename. - When merging a separate source, existing destination IDs are skipped rather than overwritten, and totals are printed.
- In-place migration upgrades existing records.
- The command does not create Discord posts or change their tags.
After migrating, verify the printed counts, restart the bot, and run /searchcases.
Storage, recovery, and backups
Case records are stored in data/cases.json, and punishment cursors in data/punishment-sync.json. There is no external case database. Writes use a temporary file and rename, and a case file that cannot be parsed raises an error instead of silently replacing your evidence with an empty store.
Forum recovery
On startup and every five minutes, the bot scans active and archived public posts in the evidence forum. It can recover recognizable bot case IDs, player details, status, and starter evidence.
- Existing records remain authoritative.
- Recovery does not reconstruct follow-up messages, assignments, or complete audit history.
- Deleted or inaccessible Discord threads do not delete stored records. Case exports remain available, while operations that need the thread report an error.
Backups and hosting moves
Keep data/cases.json and data/punishment-sync.json together. The first contains case records; the second tracks imported punishment rows. Restoring only one can cause missing records or duplicate imports.
Stop the bot
Stop the running process cleanly before copying files.
Back up the installation
Copy the full data/ directory, .env, and any customized source or addon configs. Store backups securely; they can contain private information.
Restore on the new host
Install dependencies and restore both case data and cursor data together.
Verify the move
Start a single instance and verify case lookups and forum access.
data/bot.lock is a process lock, not case data. Do not restore it.
Updating
Stop and back up
Stop the instance and take a backup of .env and data/.
Replace application files
Update the application while keeping .env, data/, and addon configs.
Install dependencies
Run npm ci from the bot directory.
Start and verify
Run npm start, check the console and test a case command. Commands re-register automatically at startup.
For error-specific checks, see Evidence Bot Troubleshooting. To edit the bot's language files, see Customizing Evidence Bot Translations.