heystreamer/INSTRUCTIONS.md

# Deployment & Git Instructions

## Prerequisites

- Python 3.10 or higher
- A Twitch account (the channel you stream on)
- Git

---

## Initial Deploy

### 1. Register a Twitch application

1. Go to [dev.twitch.tv/console/apps](https://dev.twitch.tv/console/apps)
2. Click **Register Your Application**
3. Fill in:
   - **Name:** anything (e.g. `BashyOverlay`)
   - **OAuth Redirect URLs:** `http://localhost:8000/auth/callback`
   - **Category:** Application Integration
4. Click **Create**
5. On the next screen, click **Manage** to see your app
6. Copy the **Client ID**
7. Click **New Secret** and copy the **Client Secret**

Keep both — you will need them in the next step.

---

### 2. Clone the repository

```bash
git clone https://github.com/yourusername/BashyOverlay.git
cd BashyOverlay
```

---

### 3. Configure environment variables

```bash
cp .env.example .env
```

Open `.env` and fill in:

```env
TWITCH_CLIENT_ID=paste_your_client_id_here
TWITCH_CLIENT_SECRET=paste_your_client_secret_here
TWITCH_REDIRECT_URI=http://localhost:8000/auth/callback

SECRET_KEY=paste_a_random_string_here
APP_BASE_URL=http://localhost:8000
DATABASE_URL=sqlite:///./bashyoverlay.db
```

Generate a `SECRET_KEY` with:

```bash
python3 -c "import secrets; print(secrets.token_hex(32))"
```

---

### 4. Run the deploy script

```bash
chmod +x deploy.sh
./deploy.sh
```

The script will:
- Check that Python 3.10+ is installed
- Create a `.venv` virtual environment
- Install all Python dependencies
- Verify `.env` is filled in
- Create the `static/media/` directory
- Start the server at `http://localhost:8000`

To stop the server: `Ctrl+C`

To start again without the setup steps:

```bash
source .venv/bin/activate
uvicorn app.main:app --reload
```

---

### 5. Log in with Twitch

1. Open `http://localhost:8000` in your browser
2. Click **Login with Twitch**
3. Authorise the app — you will be asked to grant permissions for subscriptions, bits, channel points, and follower data
4. You are redirected to the dashboard; EventSub connects automatically

**Bookmark the dashboard URL.** There are no accounts or passwords — the session cookie keeps you logged in.

---

### 6. Configure OBS browser source

1. In OBS, go to **Sources → + → Browser**
2. Set the URL to the value shown on the Settings page (default: `http://localhost:8000/overlay`)
3. Set **Width** and **Height** to match your stream resolution (typically `1920` × `1080`)
4. Check **Shutdown source when not visible**
5. In the **Custom CSS** box paste:
   ```css
   body { background: transparent !important; }
   ```
6. Click OK

The overlay will appear transparent in OBS. Chat messages and alerts show on top of your game/content.

---

### 7. Upload media

1. Go to **Media** in the management UI
2. Click **Choose File** and upload sounds (MP3, OGG, WAV) and/or videos (MP4, WebM)
3. Preview them in the browser before assigning them to actions

---

### 8. Configure actions

1. Go to **Actions**
2. For each event you want to react to, fill in the **Add action** form:
   - **Event type:** `sub`, `gift_sub`, `bits`, `channel_points`, `command`, `follow`, or `raid`
   - **Event detail:** command name (for commands), minimum bits (for bits), reward ID (for channel points), tier (for subs) — leave blank to match any
   - **Action type:** `sound`, `video`, or `alert`
   - **Media file:** pick an uploaded file (for sound/video)
   - **Alert text:** message shown on screen (for alert type)
   - **Cooldown:** seconds before this action can fire again
3. Click **Test** on each action to verify it fires before going live

To find a channel point reward ID: open your Twitch dashboard, go to Channel Points → Manage Rewards, then click a reward. The ID is in the page URL.

---

### 9. Configure the layout

1. Go to **Layout**
2. Drag the **Chat** handle to where you want chat to appear on screen
3. Drag the bottom-right corner of the Chat handle to resize it
4. Drag the **Alert** handle to where you want alerts to appear
5. Adjust font size, opacity, and text color in the form below the canvas
6. Click **▶ Preview alert** to see the animation with your current settings
7. Click **Save styles** when done
8. **Refresh the OBS browser source** (`Right-click source → Refresh`) to apply layout changes

---

### 10. Optional: Custom CSS and JS

Go to **Settings** and scroll to the bottom.

**Custom CSS example** — glow effect on alerts:
```css
#alert {
    box-shadow: 0 0 30px #9146ff;
    border: 2px solid #9146ff;
}
.chat-msg {
    border-left: 3px solid;
}
```

**Custom JS example** — react to a raid:
```javascript
document.addEventListener('bashyoverlay:raid', (e) => {
    console.log('Raided!', e.detail.alert_text);
});
```

Available events: `bashyoverlay:sub`, `bashyoverlay:gift_sub`, `bashyoverlay:bits`, `bashyoverlay:channel_points`, `bashyoverlay:command`, `bashyoverlay:follow`, `bashyoverlay:raid`.

Click **Save settings** then refresh the OBS browser source.

---

## Git Actions

### First push to GitHub

After creating a new empty repository on GitHub:

```bash
git remote add origin https://github.com/yourusername/BashyOverlay.git
git branch -M main
git push -u origin main
```

---

### Day-to-day workflow

```bash
# Check what has changed
git status
git diff

# Stage and commit changes
git add app/routers/actions.py templates/actions.html
git commit -m "add sub tier filtering to action matching"

# Push to remote
git push
```

---

### GitHub Actions CI

The repository includes `.github/workflows/ci.yml`. It runs automatically on every push and pull request and does the following:

1. Installs Python 3.11
2. Installs all dependencies from `requirements.txt`
3. Syntax-checks every Python file under `app/`
4. Verifies the FastAPI app imports without error

No secrets are required for CI — it uses placeholder values for Twitch credentials.

To view CI results: go to your repository on GitHub → **Actions** tab.

---

### Adding GitHub repository secrets (for future CD)

If you later want to deploy automatically, add secrets in GitHub:

1. Go to your repository → **Settings → Secrets and variables → Actions**
2. Click **New repository secret**
3. Add:
   - `TWITCH_CLIENT_ID`
   - `TWITCH_CLIENT_SECRET`
   - `SECRET_KEY`

Reference them in a workflow step with `${{ secrets.TWITCH_CLIENT_ID }}`.

---

### Branches

```bash
# Create a feature branch
git checkout -b feature/alert-interpolation

# Work, commit, push
git push -u origin feature/alert-interpolation

# Merge back to main when done (on GitHub via pull request, or locally)
git checkout main
git merge feature/alert-interpolation
git push
```

---

### Updating a deployment

If BashyOverlay is running on another machine or you pull in new changes:

```bash
git pull
source .venv/bin/activate
pip install -r requirements.txt   # in case dependencies changed
uvicorn app.main:app --reload
```

The SQLite database is updated automatically on startup — new tables and columns are created by `SQLModel.metadata.create_all`. Existing data is preserved.

> **Note:** `create_all` only adds new tables and columns — it does not handle column renames or deletions. If a migration requires dropping a column, do it manually with `sqlite3 bashyoverlay.db "ALTER TABLE ..."` before restarting.