stoat_role_bot/docs/GITEA-SETUP.md

# 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.