🖥️ Web Terminal (wterm.dev)

Browser-based terminal giving a real bash shell on the server. Accessible at https://funday.gg/dev/terminal for dev-gated users.

Architecture

flowchart TD
    Browser["Browser (wterm WASM emulator)"]
    Nginx["Nginx (/terminal-ws/)"]
    Bridge["terminal-bridge.mjs (node-pty + ws on 127.0.0.1:7681)"]
    Shell["/bin/bash -l (login shell, Funday user)"]

    Browser <-->|WebSocket (JSON, wss://)| Nginx
    Nginx <-->|ws://| Bridge
    Bridge <-->|PTY| Shell

Services

File Map

server/
└── terminal-bridge.mjs              ← WS↔PTY bridge (ESM module, node-pty + ws)

etc/systemd/system/
└── funday-terminal.service          ← systemd unit (enabled, restart-on-failure)

etc/nginx/sites-available/
└── funday                           ← contains location ^~ /terminal-ws/ { ... }

frontend/src/
├── lib/components/dev/
│   └── WTermTerminal.svelte         ← wterm.dev Svelte 5 wrapper component
├── routes/dev/terminal/
│   └── +page.svelte                 ← /dev/terminal route page
├── lib/config/
│   └── devTools.ts                  ← sidebar registry (terminal entry)
└── types/
    └── wterm.d.ts                   ← TypeScript declarations for @wterm/dom

WS Protocol

JSON frames over WebSocket. Each message: {"type": "...", ...}

Browser → Bridge

Bridge → Browser

Security

• Dev access gate — /dev/* requires Nakama auth + developer role
• Max 4 concurrent PTYs — configurable via TERMINAL_MAX_CONN
• Non-root — User=usr, NoNewPrivileges=true, ProtectSystem=strict
• Private port — bridge binds 127.0.0.1:7681 only
• TLS terminated at nginx — wss:// over the wire
• No shell escape — wterm is render-only, keystrokes via WS bridge

Operations

# Service
sudo systemctl status funday-terminal
sudo systemctl restart funday-terminal
sudo journalctl -u funday-terminal -f
 
# Health
curl -s http://127.0.0.1:7681/ | python3 -m json.tool
 
# Change max connections
sudo systemctl edit funday-terminal  # add Environment=TERMINAL_MAX_CONN=8
sudo systemctl daemon-reload && sudo systemctl restart funday-terminal

Nginx

The /terminal-ws/ proxy block in sites-available/funday:

location ^~ /terminal-ws/ {
    proxy_pass http://127.0.0.1:7681/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 86400;
    proxy_send_timeout 86400;
}

⚠️ sites-enabled/funday is a file copy, not a symlink. After editing sites-available/funday, you MUST:

sudo cp /etc/nginx/sites-available/funday /etc/nginx/sites-enabled/funday
sudo nginx -t && sudo systemctl reload nginx

Verify with: sudo nginx -T 2>/dev/null | grep terminal-ws

Troubleshooting

Gotchas

• class: directive + Tailwind / — Svelte parser treats / as division. Use inline ternary: class="bg-{status === 'ok' ? 'success' : 'error'}"
• Dynamic @wterm/dom import — must be await import() in onMount, never static (crashes SSR)
• wterm.destroy() — call in onDestroy or WASM leaks
• nginx reload ≠ pick up edits if sites-enabled/funday is stale — always cp from sites-available/

🖥️ Funday Web Terminal — Idiot Overstanding Cheat Sheet

wterm.dev browser terminal + custom PTY bridge = full bash shell at funday.gg/dev/terminal

Latest best practice as of 2026-05-31. Internal only — never expose externally.

🏗️ WHAT IT IS

A web-based terminal emulator embedded in the Funday dev zone. It gives you a real bash shell running on the server, accessible from any browser. Built with:

Full data flow:

flowchart TD
    Browser["Browser (wterm WASM)"]
    Nginx["Nginx (/terminal-ws/)"]
    Bridge["terminal-bridge.mjs (node-pty + ws on 127.0.0.1:7681)"]
    Shell["/bin/bash -l (login shell, Funday env)"]

    Browser <-->|WebSocket: JSON frames| Nginx
    Nginx <-->|ws://| Bridge
    Bridge <-->|PTY| Shell

🚀 QUICK START

Open the terminal

https://funday.gg/dev/terminal     ← requires dev access gate

Dev access = Nakama user with DEV_ACCESS_* env or “developer”/“admin” role.

Verify it’s running

# Service status
systemctl is-active funday-terminal     # → active
 
# Health check
curl -s http://127.0.0.1:7681/ | python3 -m json.tool
# → {"status":"ok","connections":0,"max":4,"uptime":...}
 
# Nginx proxy has the location
sudo nginx -T 2>/dev/null | grep "terminal-ws"
 
# WS round-trip test
python3 -c "
import asyncio, json, ssl, websockets
async def t():
    ctx = ssl.create_default_context(); ctx.check_hostname=False; ctx.verify_mode=ssl.CERT_NONE
    async with websockets.connect('wss://funday.gg/terminal-ws/ws', ssl=ctx) as ws:
        await ws.send(json.dumps({'type':'create','cols':80,'rows':24}))
        print(json.loads(await ws.recv()))         # → {"type":"created","pid":...}
        await ws.send(json.dumps({'type':'input','data':'echo ok\\n'}))
        for _ in range(15):
            m = json.loads(await asyncio.wait_for(ws.recv(), 2.0))
            if 'ok' in m.get('data',''): print('WORKS'); return
asyncio.run(t())
"

Restart after deploy

sudo systemctl restart funday-terminal    # restart bridge
sudo systemctl reload nginx             # reload proxy
# No frontend rebuild needed for bridge changes

📡 WS PROTOCOL (Bridge ↔ Browser)

JSON frames over WebSocket. Each message is {"type": ...}.

Browser → Bridge

Bridge → Browser

🛠️ OPERATIONS

Service management

sudo systemctl start|stop|restart|status funday-terminal
sudo journalctl -u funday-terminal -f           # live logs

View active connections

curl -s http://127.0.0.1:7681/ | python3 -m json.tool
# "connections": N, "max": 4

Change max connections

Edit /etc/systemd/system/funday-terminal.service:

Environment=TERMINAL_MAX_CONN=8   # default 4

Then: sudo systemctl daemon-reload && sudo systemctl restart funday-terminal

Change shell

Environment=SHELL=/bin/zsh   # default /bin/bash

🚨 CRITICAL GOTCHA: NGINX STALE FILE

/etc/nginx/sites-enabled/funday was a stale file copy (not a symlink!) from Mar 3. Edits to sites-available/funday were silently ignored by the running nginx.

ALWAYS after editing sites-available:

sudo cp /etc/nginx/sites-available/funday /etc/nginx/sites-enabled/funday
sudo nginx -t && sudo systemctl reload nginx

Verify the running config has your changes:

sudo nginx -T 2>/dev/null | grep "terminal-ws"   # must appear

🧩 ADDING TERMINAL TO A NEW DEV PAGE

1. Add entry to frontend/src/lib/config/devTools.ts:

   {
     id: "mytool",
     label: "My Tool",
     route: "/dev/mytool",
     group: "code-tools",
     icon: MyIcon,
     ...
   }

2. Create route: frontend/src/routes/dev/mytool/+page.svelte
3. Embed terminal:

   <WTermTerminal wsUrl={`${location.host}/terminal-ws/ws`} rows={24} cols={80} />

4. Rebuild frontend: bash scripts/build-atomic.sh

🔒 SECURITY

🧠 SVELTER 5 + WTERM ANTI-PATTERNS

❌ class: with Tailwind / opacity = BREAKS

<!-- ❌ WRONG — Svelte parser sees / as division -->
<span class:bg-base-content/20={status === "disconnected"} />
 
<!-- ✅ CORRECT — inline class with ternary -->
<span class="w-2 h-2 {status === 'connected' ? 'bg-success' : 'bg-base-content/20'}" />

❌ Don’t import @wterm statically for SSR

<!-- ❌ WRONG — crashes SSR (no DOM) -->
<script>import { WTerm } from "@wterm/dom";</script>
 
<!-- ✅ CORRECT — dynamic import in onMount -->
<script>import { onMount } from "svelte";
onMount(async () => {
  const { WTerm } = await import("@wterm/dom");
  await import("@wterm/dom/css");
  ...
});
</script>

❌ Don’t forget wterm.destroy() in onDestroy

Memory leak — the WASM terminal keeps rendering in the background.

📁 FILE MAP

server/
└── terminal-bridge.mjs          ← 🖥️ WS↔PTY bridge (ESM, port 7681)

frontend/src/
├── lib/components/dev/
│   └── WTermTerminal.svelte     ← 🎨 wterm Svelte wrapper component
├── lib/config/
│   └── devTools.ts              ← 📋 dev sidebar registry (terminal entry)
├── routes/dev/terminal/
│   └── +page.svelte             ← 📄 /dev/terminal route
└── types/
    └── wterm.d.ts               ← 📝 TypeScript declarations

/etc/nginx/sites-available/funday  ← 🔀 nginx config (TERMINAL BLOCK)
/etc/systemd/system/funday-terminal.service  ← ⚙️ systemd unit

🎨 TERMINAL THEMES

wterm ships 4 built-in themes (CSS class on .wterm):

The terminal CSS auto-bundled from @wterm/dom/css into terminal.BCS3iTzZ.css at build time.

🆘 TROUBLESHOOTING