132 lines
5.6 KiB
Markdown
132 lines
5.6 KiB
Markdown
|
# 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.
|