jasonwitty
6e48c095ab
- Multi-architecture Docker image (ARM64 + AMD64) - Kubernetes manifests for 3-replica deployment - Traefik ingress configuration - NGINX Proxy Manager integration - ConfigMap-based configuration - Automated build and deployment scripts - Session monitoring tools
235 lines
5.9 KiB
Markdown
235 lines
5.9 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
cp static/terminado-addon.js node_modules/
|
|
```
|
|
|
|
This makes our custom Terminado WebSocket addon available to the server.
|
|
|
|
### Step 3: Build the Rust Backend
|
|
|
|
```bash
|
|
cargo build
|
|
```
|
|
|
|
### Step 4: Run the Server
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
./verify_upgrade.sh
|
|
```
|
|
|
|
All checks should pass with green checkmarks ✓
|
|
|
|
## Command Line Options
|
|
|
|
The server supports several command-line options:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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) |