matt/echo6-docs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
echo6-docs/projects/openwebui-theme-deploy.md
Matt Johnson e9231ac24a Migration: consolidate Echo6 docs to cortex with full infrastructure cleanup sync 
- Documents recent infrastructure cleanup (8 CTs destroyed, 35 DNS records removed, Headscale cleanup)
- Adds 24 new runbooks covering Authentik, PeerTube, Meshtastic, RECON, Proxmox, Mailcow, Internet Archive, GPU routing
- Adds project documentation for headscale, vaultwarden, peertube, matrix, mmud, advbbs, arr stack
- Updates services.md, environment.md, caddy.md, authentik.md to match live infrastructure
- Removes 4 deprecated runbook duplicates (canonical versions live in projects/)
- Adds .gitignore for binary archives and editor temp files

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-13 06:02:16 +00:00

5.6 KiB
Raw Blame History

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:

    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:

    #!/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

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:

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

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

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:

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:

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.