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

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

---

3. Configure environment variables

cp .env.example .env

Open .env and fill in:

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:

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

---

4. Run the deploy script

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:

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:

   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:

#alert {
    box-shadow: 0 0 30px #9146ff;
    border: 2px solid #9146ff;
}
.chat-msg {
    border-left: 3px solid;
}

Custom JS example — react to a raid:

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:

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

---

Day-to-day workflow

# 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

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

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.