socktop-webterm/QUICKSTART.md

Quick Start Guide

xterm.js 5.5.0 Upgrade - Quick Start

This guide will get you up and running with the upgraded xterm.js terminal in minutes.

Prerequisites

• Rust and Cargo installed
• Node.js and npm installed
• A terminal/command line

Installation & Running

Step 1: Install npm Dependencies

npm install

This installs:

• @xterm/xterm v5.5.0 (the main terminal library)
• @xterm/addon-fit v0.10.0 (auto-sizing addon)

Step 2: Copy Custom Addon

cp static/terminado-addon.js node_modules/

This makes our custom Terminado WebSocket addon available to the server.

Step 3: Build the Rust Backend

cargo build

Step 4: Run the Server

cargo run

The server will start on http://127.0.0.1:8082 (localhost:8082)

Step 5: Open in Browser

Navigate to: http://localhost:8082/

You should see:

• A terminal that auto-launches socktop -P local
• A properly sized terminal that fits the window
• A responsive terminal that resizes with the browser window

Verify the Upgrade

Run the verification script to ensure everything is set up correctly:

./verify_upgrade.sh

All checks should pass with green checkmarks ✓

Command Line Options

The server supports several command-line options:

# Run on a different port
cargo run -- --port 8080

# Run on all interfaces (0.0.0.0)
cargo run -- --host 0.0.0.0

# Use a different command
cargo run -- --command /bin/bash

# Combine options
cargo run -- --host 0.0.0.0 --port 8080 --command /bin/zsh

Testing the Terminal

Open the standalone test page to verify xterm.js is working:

# Start a simple HTTP server
python3 -m http.server 8000

# Open in browser
# http://localhost:8000/test_xterm.html

This test page verifies:

• xterm.js 5.5.0 loads correctly
• FitAddon works
• Terminal accepts input
• Modern API is functional

What Changed from 3.14.5 to 5.5.0?

Package Names

• Old: xterm
• New: @xterm/xterm (scoped package)

Addon System

• Old: Terminal.applyAddon(fit) → term.fit()
• New: term.loadAddon(new FitAddon()) → fitAddon.fit()

File Locations

• Old: xterm/dist/xterm.js
• New: @xterm/xterm/lib/xterm.js

Custom Terminado Addon

We created a modern TerminadoAddon class that implements the new ITerminalAddon interface to handle WebSocket communication with the backend.

Architecture

┌─────────────────┐
│   Browser       │
│  (JavaScript)   │
│                 │
│  ┌───────────┐  │
│  │ xterm.js  │  │
│  │  v5.5.0   │  │
│  └─────┬─────┘  │
│        │        │
│  ┌─────▼─────┐  │
│  │ FitAddon  │  │
│  └───────────┘  │
│        │        │
│  ┌─────▼─────┐  │
│  │ Terminado │  │
│  │   Addon   │  │
│  └─────┬─────┘  │
└────────┼────────┘
         │ WebSocket
         │ (JSON messages)
┌────────▼────────┐
│  Rust Backend   │
│                 │
│  ┌───────────┐  │
│  │ actix-web │  │
│  └─────┬─────┘  │
│        │        │
│  ┌─────▼─────┐  │
│  │ Terminado │  │
│  │  Protocol │  │
│  └─────┬─────┘  │
│        │        │
│  ┌─────▼─────┐  │
│  │    PTY    │  │
│  └─────┬─────┘  │
│        │        │
│  ┌─────▼─────┐  │
│  │  socktop  │  │
│  └───────────┘  │
└─────────────────┘

Troubleshooting

Terminal doesn't display

• Check browser console for JavaScript errors
• Verify WebSocket connection in DevTools Network tab
• Ensure server is running on the correct port

Resources fail to load (404 errors)

• Run npm install to ensure packages are installed
• Verify terminado-addon.js is in node_modules/
• Check file paths in templates/term.html

Terminal doesn't fit window

• FitAddon may not be loading correctly
• Check that fitAddon.fit() is called after terminal is opened
• Verify container has non-zero dimensions

Rust compile errors

• Update Rust: rustup update
• Clean build: cargo clean && cargo build

WebSocket connection fails

• Check firewall settings
• Try binding to 127.0.0.1 instead of localhost
• Verify port 8082 is not in use

Next Steps

Now that xterm.js is upgraded, you can:

1. Customize the terminal appearance

   • Modify colors in templates/term.html
   • Change font size and family
   • Adjust terminal dimensions

2. Add more features

   • Install additional xterm addons
   • Implement search functionality
   • Add web link support

3. Build your website

   • Use this as a foundation for your socktop website
   • Add navigation and branding
   • Implement user authentication

4. Deploy to production

   • Set up HTTPS (required for secure WebSockets)
   • Configure proper firewall rules
   • Consider adding authentication

Additional Resources

• Full Documentation: See XTERM_UPGRADE.md
• Upgrade Details: See UPGRADE_SUMMARY.md
• Verification: Run ./verify_upgrade.sh
• Test Page: Open test_xterm.html in browser

Getting Help

If you run into issues:

1. Run the verification script: ./verify_upgrade.sh
2. Check the browser console for errors
3. Review server logs for backend issues
4. Consult the detailed documentation in XTERM_UPGRADE.md

---

Status: ✅ Upgrade Complete
xterm.js Version: 5.5.0
FitAddon Version: 0.10.0
Backend: Rust + actix-web (no changes required)