# RUNBOOK — Deploy Echo6 Theme to Open WebUI

> **STATUS: COMPLETED** — 2026-02-17
> Theme deployed to https://ai.echo6.co. Open WebUI runs in Docker (not native as originally stated).
> Theme files bind-mounted from `/home/zvx/echo6-theme/` into container via docker-compose.yml.
> Compose path: `/opt/open-webui/docker-compose.yml` on cortex.

## OBJECTIVE
Apply the togglable Echo6 custom CSS theme to the Open WebUI instance running at ai.echo6.co. The instance runs in Docker on the `cortex` VM. The theme is toggled on/off via a small "E6" button in the bottom-right corner, with the preference persisted in localStorage per browser.

## THEME FILES
Located in this project's reference assets:
```
.ref/assets/echo6-openwebui-theme.css   # Theme styles (activates via .echo6 class on <html>)
.ref/assets/echo6-theme-toggle.js       # Toggle button + localStorage persistence
```

## SAFETY FIRST — BACKUP BEFORE ANYTHING

Before making ANY changes:

1. **Find the Open WebUI static build directory.** Likely locations:
   - Check: `pip show open-webui 2>/dev/null` for the install path
   - Search: `find / -name "index.html" -path "*/open*webui*" 2>/dev/null`
   - Search: `find / -name "app.html" -path "*/open*webui*" 2>/dev/null`
   - Common pip paths: `/usr/lib/python3/dist-packages/open_webui/static/`

2. Once found, identify the **root HTML file** (likely `index.html` or `app.html`).

3. **Create a timestamped backup:**
   ```bash
   OWUI_DIR="/path/to/open-webui/build"  # ← set this once found
   BACKUP_DIR="/home/matt/backups/openwebui-theme-$(date +%Y%m%d-%H%M%S)"
   mkdir -p "$BACKUP_DIR"
   cp -a "$OWUI_DIR" "$BACKUP_DIR/"
   echo "Backed up to: $BACKUP_DIR"
   ```

4. **Create a revert script** at `/home/matt/revert-openwebui-theme.sh`:
   ```bash
   #!/bin/bash
   # Revert Echo6 theme — restores original Open WebUI files
   BACKUP_DIR="<populated during deploy>"
   OWUI_DIR="<populated during deploy>"
   echo "[REVERT] Restoring Open WebUI from $BACKUP_DIR"
   cp -a "$BACKUP_DIR"/* "$OWUI_DIR/"
   echo "[REVERT] Done. Restart Open WebUI service if needed."
   ```
   Make it executable: `chmod +x /home/matt/revert-openwebui-theme.sh`

## DEPLOYMENT STEPS

### Step 1: Copy theme files to Open WebUI static directory
```bash
cp .ref/assets/echo6-openwebui-theme.css "$OWUI_DIR/static/"
cp .ref/assets/echo6-theme-toggle.js "$OWUI_DIR/static/"
```
Also keep persistent copies that survive upgrades:
```bash
mkdir -p /home/matt/echo6-theme
cp .ref/assets/echo6-openwebui-theme.css /home/matt/echo6-theme/
cp .ref/assets/echo6-theme-toggle.js /home/matt/echo6-theme/
```

### Step 2: Inject into the root HTML
Find the root HTML file and add BOTH a `<link>` and a `<script>` tag BEFORE `</head>`:
```bash
sed -i 's|</head>|<link rel="stylesheet" href="/static/echo6-openwebui-theme.css">\n<script src="/static/echo6-theme-toggle.js" defer></script>\n</head>|' "$OWUI_DIR/index.html"
```

**IMPORTANT:** Check existing `<link>` and `<script>` tags in the HTML first to confirm the `/static/` prefix matches how Open WebUI serves assets. Adjust the path if it uses a different pattern (e.g. `/_app/`, `/build/`, etc.).

### Step 3: Verify
```bash
grep "echo6" "$OWUI_DIR/index.html"
ls -la "$OWUI_DIR/static/echo6-openwebui-theme.css"
ls -la "$OWUI_DIR/static/echo6-theme-toggle.js"
```

Restart the service if needed:
```bash
sudo systemctl restart open-webui   # or whatever the service name is
```

### Step 4: Test
- `curl -s https://ai.echo6.co | grep echo6` should show both the CSS and JS references
- Load ai.echo6.co in browser — should see a small "E6" button in the bottom-right corner
- Click it: theme activates (dark bg, cyan accents, JetBrains Mono)
- Click again: reverts to stock Open WebUI appearance
- Refresh page: preference should persist

## HOW THE TOGGLE WORKS

1. The JS injects a fixed-position "E6" button at bottom-right
2. Clicking it toggles the `echo6` class on `<html>`
3. ALL CSS selectors in the theme are `.echo6 <target>` — they ONLY fire when that class is present
4. The toggle state is saved to `localStorage` under the key `echo6-theme-active`
5. On page load, the JS reads localStorage and restores the previous state before first paint
6. Open WebUI's built-in theme picker (Light/Dark/OLED) still works independently

## CONSTRAINTS / DO NOT

- Do NOT modify any Open WebUI Python source code
- Do NOT modify any existing JavaScript files
- Do NOT install additional packages
- Do NOT change Open WebUI configuration/database
- ONLY touch: one HTML file (add one `<link>` + one `<script>` tag) and add two static files
- If anything looks wrong or the build structure is unexpected, STOP and report back

## DEBUGGING

If the theme doesn't apply:
1. Browser dev tools → Network tab — are both files loading? (200 vs 404)
2. Browser dev tools → Elements → check `<html>` — does it have class `echo6` after clicking toggle?
3. Browser dev tools → Console — any JS errors?
4. If selectors don't match the actual DOM, inspect elements and adjust selectors in the CSS

If the toggle button doesn't appear:
1. Check Console for JS errors
2. Verify the `<script>` tag is present in the HTML source
3. Check if the JS file path is correct (404 in Network tab)

## AFTER UPGRADE PROCEDURE

After any Open WebUI upgrade, the build files get overwritten. To re-apply:
```bash
cp /home/matt/echo6-theme/echo6-openwebui-theme.css "$OWUI_DIR/static/"
cp /home/matt/echo6-theme/echo6-theme-toggle.js "$OWUI_DIR/static/"
# Re-inject the tags into the HTML:
sed -i 's|</head>|<link rel="stylesheet" href="/static/echo6-openwebui-theme.css">\n<script src="/static/echo6-theme-toggle.js" defer></script>\n</head>|' "$OWUI_DIR/index.html"
```
Or just re-run this runbook from the top.
