Initial commit: Stoat Role Bot

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-17 19:45:23 -06:00
commit 09e3b6ca66
16 changed files with 1312 additions and 0 deletions
@@ -0,0 +1,119 @@
+# Deploying Stoat Role Bot on a UGREEN DXP4800 Plus NAS
+
+The DXP4800 Plus runs **UGOS Pro** and supports Docker. Below are two ways to run the bot.
+
+---
+
+## Option A: SSH + Docker Compose (recommended if SSH is enabled)
+
+If your NAS has **SSH** and **Docker** (and optionally **Docker Compose**) enabled:
+
+1. **Copy the project to the NAS**
+   - Use **SMB/CIFS**: copy the whole `Role Bot` folder to a share (e.g. `Docker` or `Containers`).
+   - Or from your PC with SSH:  
+     `scp -r "/path/to/Role Bot" admin@<NAS_IP>:~/stoat-role-bot`
+
+2. **SSH into the NAS**
+   ```bash
+   ssh admin@<NAS_IP>
+   cd ~/stoat-role-bot   # or the path where you copied the project
+   ```
+
+3. **Ensure `.env` and config exist**
+   - `.env` with `STOAT_BOT_TOKEN=...` (and optional `PREFIX=!`)
+   - `config/roles.json` (copy from `config/roles.json.example` and edit server ID / message ID)
+
+4. **Run with Docker**
+   - If **Docker Compose** is installed:
+     ```bash
+     docker compose up -d
+     ```
+   - If only **Docker** is available, build and run manually:
+     ```bash
+     docker build -t stoat-role-bot .
+     docker run -d --name stoat-role-bot --restart unless-stopped \
+       -e STOAT_BOT_TOKEN="$(grep STOAT_BOT_TOKEN .env | cut -d= -f2)" \
+       -e PREFIX=! \
+       -v "$(pwd)/config:/app/config:rw" \
+       stoat-role-bot
+     ```
+
+5. **Check logs**
+   ```bash
+   docker logs -f stoat-role-bot
+   ```
+
+---
+
+## Option B: NAS App Center / Docker UI (no SSH)
+
+If you manage containers only through the **UGREEN web UI** (App Center / Docker):
+
+### Step 1: Build the image on your PC, then transfer
+
+On your **PC** (where you have the project):
+
+```bash
+cd "/path/to/Role Bot"
+docker build -t stoat-role-bot:latest .
+docker save stoat-role-bot:latest -o stoat-role-bot.tar
+```
+
+Copy `stoat-role-bot.tar` to a shared folder on the NAS (e.g. via SMB).
+
+### Step 2: Load image and create container on the NAS
+
+1. In **UGOS Pro**, open **App Center** (or **Container** / **Docker**).
+2. **Load** the image:
+   - Look for “Import image” / “Load image” and select `stoat-role-bot.tar` from the share.
+3. **Create a container** from that image:
+   - **Name**: e.g. `stoat-role-bot`
+   - **Restart policy**: “Unless stopped” or “Always”
+   - **Environment variables** (add each):
+     - `STOAT_BOT_TOKEN` = `your_bot_token_from_env_file`
+     - `PREFIX` = `!`
+     - `CONFIG_PATH` = `/app/config`
+   - **Volume / bind mount**:
+     - Host path: a folder where you will put `roles.json` (e.g. `/share/Containers/stoat-role-bot/config` or a path shown in the UI).
+     - Container path: `/app/config`
+   - No port mapping is needed (bot only makes outbound connections).
+
+4. Put your **config** on the NAS:
+   - In that host path, create `roles.json` (copy from `roles.json.example` and set your server ID and message ID).
+
+5. Start the container.
+
+---
+
+## Option C: Use a pre-built image (if you publish to Docker Hub)
+
+If you push the image to **Docker Hub** (or another registry the NAS can use):
+
+1. On your PC:
+   ```bash
+   docker build -t YOUR_USERNAME/stoat-role-bot:latest .
+   docker push YOUR_USERNAME/stoat-role-bot:latest
+   ```
+2. On the NAS (SSH or App Center): create a container from image `YOUR_USERNAME/stoat-role-bot:latest` with the same **env vars** and **volume** as in Option B.
+
+Then the NAS only needs to pull the image; no build on the NAS.
+
+---
+
+## Notes for UGREEN NAS
+
+- **Networking**: This bot only needs outbound HTTPS/WebSocket to Stoat/Revolt. No inbound ports or port mapping are required.
+- **Reboots**: Use restart policy “Unless stopped” so the bot starts again after a NAS reboot.
+- **Config backup**: Back up the `config` folder (and `.env` if you keep it on the NAS) so you don’t lose roles configuration.
+- **UGOS / Docker issues**: If the NAS Docker stack has known issues, prefer building and running via SSH (Option A) or using a pre-built image (Option C) so the NAS doesn’t have to build the image.
+
+---
+
+## Quick checklist
+
+- [ ] Project (or image) on the NAS
+- [ ] `.env` with `STOAT_BOT_TOKEN` (or env vars set in the container)
+- [ ] `config/roles.json` with your server ID and reaction-role message ID
+- [ ] Volume mapping: host `config` → `/app/config`
+- [ ] Container set to restart unless stopped
+- [ ] Logs show “Logged in as …” and no errors