stoat_role_bot/DEPLOY-NAS.md

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

   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:

     docker compose up -d
     

   • If only Docker is available, build and run manually:

     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

   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):

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:

   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.

---

Option D: Pull from Gitea Container Registry (recommended)

The repo’s Gitea Actions build the image and push it to the Gitea registry. Use this image on your NAS so you always run the latest build.

Image: brassnet.ddns.net:33983/dawnsorrow/stoat-role-bot:latest
(Registry image names are lowercase; use dawnsorrow.)

On the NAS (so the image appears in your Docker app)

1. Add the registry as insecure (HTTP)
   If your Gitea is HTTP (no HTTPS), Docker must allow this registry:

   • In UGOS Pro: find Docker/Container settings (sometimes under “Registry” or “Docker daemon”) and add brassnet.ddns.net:33983 to insecure registries.
   • Or via SSH, edit Docker daemon config to include:

     "insecure-registries": ["brassnet.ddns.net:33983"]
     

   • Restart Docker (or the NAS) if required.

2. Log in to the registry (so pull works)

   • In the Docker / App Center UI: look for “Registry” or “Login” and add:
     • Registry: brassnet.ddns.net:33983
     • Username: your Gitea username (e.g. Dawnsorrow)
     • Password: your Gitea password (or a token with package read)
   • Or via SSH:

     docker login brassnet.ddns.net:33983
     

     Use your Gitea username and password when prompted.

3. Pull the image

   • In the UI: use “Pull image” (or similar) and enter: brassnet.ddns.net:33983/dawnsorrow/stoat-role-bot:latest
   • Or via SSH:

     docker pull brassnet.ddns.net:33983/dawnsorrow/stoat-role-bot:latest
     

4. Create and run the container
   Same as Option B: create a container from the image above with:

   • Name: e.g. stoat-role-bot
   • Restart: Unless stopped
   • Environment: STOAT_BOT_TOKEN, PREFIX=!, CONFIG_PATH=/app/config
   • Volume: host folder with roles.json → /app/config

5. Updates
   To get the newest version: pull again (docker pull brassnet.ddns.net:33983/dawnsorrow/stoat-role-bot:latest or “Pull” in the UI), then recreate or restart the container.

---

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