Evidence BotMaintenance & Backups

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 cases table and an optional followUps table.

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

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 .bak file, 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.