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**
   ```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.

---

## 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:
     ```json
     "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:
     ```bash
     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:
     ```bash
     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