stoat_role_bot/LOCAL-TEST.md

Local testing (verify bot works before/without NAS)

Run the bot on your PC with the same token and config. If it works locally but not on the NAS, the issue is NAS/container. If it fails locally too, the issue is token, config, or Stoat server.

---

1. Run with Node.js (fastest)

On your PC, in the project folder:

cd "/home/jorg/Documents/Cursor Projects/Role Bot"

# Use the same .env as NAS (token must be set)
export $(grep -v '^#' .env | xargs)
export CONFIG_PATH=./config

# Optional: see every message the bot receives (for debugging)
export DEBUG=1

# Install and run
npm install
npm start

You should see:

• Connecting to Stoat/Revolt API...
• Logged in as ExodusMigrator — bot is online
• With DEBUG=1, lines like Message: !roles [command] when you type in Stoat

Test in Stoat: In a channel the bot can see, send:

• !roles → bot should reply (list of roles or “No self-assignable roles…”).
• If you have assignable roles set in config/roles.json, try !role add <RoleName>.

Stop with Ctrl+C.

---

2. Run with Docker/Podman (same as NAS)

Same setup as the NAS, but on your machine:

cd "/home/jorg/Documents/Cursor Projects/Role Bot"

# Ensure .env has STOAT_BOT_TOKEN and config/roles.json exists
docker compose up
# or: podman compose up

Leave it running and test !roles in Stoat. Stop with Ctrl+C (or docker compose down in another terminal).

---

3. What to check

Result	Meaning
Local Node: bot replies to !roles	Bot and token are fine; problem is likely NAS/container (network or env).
Local Node: no reply to !roles	Check: (1) config/roles.json has correct server ID for your Stoat server, (2) bot is in that server and has a role above the roles it assigns, (3) channel is in that server.
Local Node: "Login failed" or crash	Token invalid/revoked or network block; fix token or firewall.
Local works, NAS doesn’t	On NAS: confirm STOAT_BOT_TOKEN is set in the container, and that the NAS can reach the internet (no block on outbound HTTPS).

---

4. Get your server ID for config

If !roles says "No self-assignable roles" or "Configured role names don't match", your config/roles.json may have the wrong server ID.

In Stoat (web): open your server, check the URL. It often looks like: https://app.revolt.chat/server/01ABC123...
The long ID after /server/ is your server ID. Use it in config/roles.json:

{
  "servers": {
    "01ABC123_YOUR_REAL_SERVER_ID": {
      "reaction_roles": {},
      "assignable_roles": ["Notifications", "Gamer"]
    }
  }
}

Role names under assignable_roles must match the exact role names in your Stoat server (case-sensitive).

---

5. Optional: DEBUG when running on NAS

To see incoming messages in the NAS container logs, add this env var when creating the container:

• DEBUG=1

Then in the logs you’ll see when the bot receives a message (and whether it’s treated as a command). Helps confirm if the bot gets events at all on the NAS.