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,192 @@
+# Simple Gitea setup for Stoat Role Bot
+
+This guide assumes you have a Gitea server (e.g. `https://gitea.yourdomain.com`) and want the bot’s Docker image to be built and stored there so your NAS can pull it.
+
+---
+
+## Your exact values (copy-paste)
+
+| What | Value |
+|------|--------|
+| **Gitea URL** | `http://brassnet.ddns.net:33983` |
+| **Username** | `Dawnsorrow` |
+| **Registry host** (for Docker/Podman) | `brassnet.ddns.net:33983` |
+| **Full image name** (after workflow runs) | `brassnet.ddns.net:33983/Dawnsorrow/stoat-role-bot:latest` |
+
+**Git remote** (from your PC, in the bot project folder):
+```bash
+git remote add origin http://brassnet.ddns.net:33983/Dawnsorrow/stoat-role-bot.git
+```
+
+**On your NAS** – in `.env` add:
+```
+GITEA_IMAGE=brassnet.ddns.net:33983/Dawnsorrow/stoat-role-bot:latest
+```
+
+**Gitea repo Settings → Secrets** – create:
+- **REGISTRY_USER** = `Dawnsorrow`
+- **REGISTRY_PASSWORD** = your Gitea password (or a Personal Access Token)
+
+**Manual push from PC** (if you’re not using Actions):
+```bash
+export GITEA_REGISTRY=brassnet.ddns.net:33983
+export GITEA_OWNER=Dawnsorrow
+./push-to-gitea.sh
+```
+
+---
+
+## What you’re doing in one sentence
+
+You’ll put this bot’s code in a Gitea **repository**, add two **secrets** (username + password), and then every time you **push** to the repo, Gitea will **build** the Docker image and **publish** it to its built-in container registry. Your NAS will **pull** that image and run it.
+
+---
+
+## Part 1: Create the repository in Gitea
+
+1. Log in to your Gitea in the browser.
+2. Click **“+”** (or **New**) → **New Repository**.
+3. Fill in:
+   - **Repository name:** `stoat-role-bot` (or any name you like).
+   - **Visibility:** Private or Public (your choice).
+   - Leave “Initialize repository” **unchecked** if you already have the code on your PC.
+4. Click **Create Repository**.
+
+You’ll see an empty repo (or a page with clone/push instructions). That’s your “home” for this bot’s code.
+
+---
+
+## Part 2: Push this project’s code to that repository
+
+From your PC, in the folder where the bot code lives (the one with `bot/`, `Dockerfile`, `.gitea/`, etc.):
+
+1. If this folder is **not** a git repo yet:
+   ```bash
+   cd "/home/jorg/Documents/Cursor Projects/Role Bot"
+   git init
+   git add .
+   git commit -m "Initial commit: Stoat Role Bot"
+   ```
+2. Add Gitea as the remote (replace with **your** Gitea URL and username):
+   ```bash
+   git remote add origin https://gitea.yourdomain.com/YOUR_USERNAME/stoat-role-bot.git
+   ```
+   Example: if your Gitea is `https://git.myserver.com` and your username is `jorg`:
+   ```bash
+   git remote add origin https://git.myserver.com/jorg/stoat-role-bot.git
+   ```
+3. Push the code:
+   ```bash
+   git push -u origin main
+   ```
+   If your branch is named `master` instead of `main`, use:
+   ```bash
+   git push -u origin master
+   ```
+
+After this, the bot’s code (including the Dockerfile and the workflow file) is in Gitea.
+
+---
+
+## Part 3: Turn on Gitea Actions (if your instance has it)
+
+1. In Gitea, open **your user menu** (top right) → **Site Administration** (only if you’re an admin).
+2. Or ask your Gitea admin: “Is **Actions** enabled for this instance?”
+3. For **this repo**: go to the repo → **Settings** → check for an **Actions** or **Workflows** section. If you see “Actions” or “Workflows” and they’re enabled, you’re good.
+
+If Actions are **not** available, you can skip the automated build and use the **manual push** method at the end instead.
+
+---
+
+## Part 4: Add the two “secrets” (so Gitea can push to its own registry)
+
+Gitea needs to log in to its **container registry** to push the image. You give it your credentials as **secrets** (so they’re not written in the code).
+
+1. In your repo on Gitea, go to **Settings** (repo menu or top tabs).
+2. In the left sidebar, click **Secrets** (or **Secrets and Variables**).
+3. Add **two** secrets:
+
+| Name                 | Value                    | Notes |
+|----------------------|--------------------------|--------|
+| `REGISTRY_USER`      | Your Gitea **username**  | The one you use to log in. |
+| `REGISTRY_PASSWORD`  | Your Gitea **password**  | Or a **Personal Access Token** (see below). |
+
+**Using a token instead of password (recommended):**
+
+1. In Gitea: your **profile icon** (top right) → **Settings** → **Applications** → **Generate New Token**.
+2. Name it e.g. `stoat-bot-registry`, enable **write:package** (or “packages”) if you see it, then create the token.
+3. Copy the token and use it as the value for **REGISTRY_PASSWORD** (leave REGISTRY_USER as your username).
+
+After saving both secrets, the workflow can log in to the registry when it runs.
+
+---
+
+## Part 5: What happens when you push
+
+- The workflow file is in **`.gitea/workflows/docker.yml`**.
+- When you **push to `main`** (or `master`), Gitea runs that workflow:
+  1. It builds the Docker image from the Dockerfile in the repo.
+  2. It logs in to Gitea’s container registry using the two secrets.
+  3. It pushes the image as: **`{your-gitea-host}/{your-username}/stoat-role-bot:latest`**
+
+Example: if your Gitea URL is `https://git.myserver.com` and your username is `jorg`, the image will be:
+
+**`git.myserver.com/jorg/stoat-role-bot:latest`**
+
+(no `https://` in the image name)
+
+---
+
+## Part 6: Use that image on your NAS
+
+1. On the NAS, create a folder for the bot (e.g. `stoat-role-bot`) and put there:
+   - **config/** (with your `roles.json`).
+   - **.env** with at least:
+     - `STOAT_BOT_TOKEN=your_bot_token`
+     - `GITEA_IMAGE=git.myserver.com/jorg/stoat-role-bot:latest`  
+       (use **your** Gitea host and username).
+2. Copy into that folder the file **`docker-compose.pull.yml`** from this repo.
+3. In that folder, run:
+   ```bash
+   docker compose -f docker-compose.pull.yml pull
+   docker compose -f docker-compose.pull.yml up -d
+   ```
+
+If your Gitea is only reachable on your LAN, the NAS must be able to reach that host (e.g. `git.myserver.com` or your server’s IP). If the registry is private, you may need to run `docker login git.myserver.com` on the NAS once (with your Gitea username and password/token).
+
+**HTTP (no HTTPS):** If your Gitea is at `http://...` (like `http://brassnet.ddns.net:33983`), Docker may treat the registry as “insecure.” On the NAS you might need to add that host to Docker’s insecure registries (e.g. in `/etc/docker/daemon.json`: `"insecure-registries": ["brassnet.ddns.net:33983"]`) and restart Docker, then run `docker login brassnet.ddns.net:33983` with your Gitea username and password.
+
+---
+
+## If Gitea Actions aren’t available: manual push
+
+You can build and push the image from your PC instead of using Actions:
+
+1. Install Podman (or Docker) and log in to Gitea’s registry:
+   ```bash
+   podman login git.myserver.com
+   ```
+   Use your Gitea username and password (or token).
+
+2. From the bot project folder:
+   ```bash
+   export GITEA_REGISTRY=git.myserver.com
+   export GITEA_OWNER=jorg
+   ./push-to-gitea.sh
+   ```
+   Replace `git.myserver.com` and `jorg` with your Gitea host and username.
+
+3. On the NAS, use the same image name as above and run the same `docker compose -f docker-compose.pull.yml` commands.
+
+---
+
+## Quick checklist
+
+- [ ] Repo created in Gitea.
+- [ ] Code pushed to that repo (`git push origin main`).
+- [ ] Actions enabled (if available).
+- [ ] Secrets **REGISTRY_USER** and **REGISTRY_PASSWORD** added in repo Settings.
+- [ ] After a push, the workflow runs and the image appears under the repo’s **Packages** (or **Container registry**).
+- [ ] On the NAS: **GITEA_IMAGE** set in `.env`, then `docker compose -f docker-compose.pull.yml pull && up -d`.
+
+If you tell me your Gitea URL and username (e.g. `git.myserver.com` and `jorg`), I can give you the exact commands and `.env` line with those values filled in.