diff --git a/CATPPUCCIN_STYLING.md b/CATPPUCCIN_STYLING.md deleted file mode 100644 index 225fe26..0000000 --- a/CATPPUCCIN_STYLING.md +++ /dev/null @@ -1,390 +0,0 @@ -# Catppuccin Frappe Styling Guide - -## Overview - -The socktop website now uses the beautiful **Catppuccin Frappe** color scheme throughout. This guide documents all the colors and styling conventions used. - -## Color Palette - -### Base Colors -```css ---ctp-base: #303446; /* Main background */ ---ctp-mantle: #292c3c; /* Slightly darker background */ ---ctp-crust: #232634; /* Darkest background */ -``` - -### Surface Colors -```css ---ctp-surface0: #414559; /* UI elements background */ ---ctp-surface1: #51576d; /* Slightly lighter UI elements */ ---ctp-surface2: #626880; /* Even lighter UI elements */ -``` - -### Overlay Colors -```css ---ctp-overlay0: #737994; /* Disabled text */ ---ctp-overlay1: #838ba7; /* Comments, secondary text */ ---ctp-overlay2: #949cbb; /* Tertiary text */ -``` - -### Text Colors -```css ---ctp-text: #c6d0f5; /* Primary text */ ---ctp-subtext1: #b5bfe2; /* Secondary text */ ---ctp-subtext0: #a5adce; /* Tertiary text */ -``` - -### Accent Colors -```css ---ctp-lavender: #babbf1; /* Links, highlights */ ---ctp-blue: #8caaee; /* Information, primary actions */ ---ctp-sapphire: #85c1dc; /* Special highlights */ ---ctp-sky: #99d1db; /* Sky blue accent */ ---ctp-teal: #81c8be; /* Teal accent */ ---ctp-green: #a6d189; /* Success, positive */ ---ctp-yellow: #e5c890; /* Warnings, attention */ ---ctp-peach: #ef9f76; /* Rust/crates.io theme */ ---ctp-maroon: #ea999c; /* Darker red variant */ ---ctp-red: #e78284; /* Errors, close button */ ---ctp-mauve: #ca9ee6; /* Primary brand color */ ---ctp-pink: #f4b8e4; /* Pink accent */ ---ctp-flamingo: #eebebe; /* Lighter pink */ ---ctp-rosewater: #f2d5cf; /* Lightest pink, cursor */ -``` - -## Component Styling - -### Hero Title -- **Gradient**: Mauve to Blue (`#ca9ee6` → `#8caaee`) -- **Font**: 3rem, weight 800 -- **Effect**: Text gradient with subtle glow -- **Usage**: Main "socktop" heading - -### Tagline -- **Color**: `var(--ctp-subtext1)` (#b5bfe2) -- **Font**: 1.25rem, weight 400 -- **Usage**: "A TUI-first remote system monitor." - -### Link Buttons - -#### Base Style -```css -background: rgba(65, 69, 89, 0.6); -border: 1px solid rgba(186, 187, 241, 0.2); -border-radius: 12px; -color: var(--ctp-text); -``` - -#### GitHub Button -- **Border hover**: `var(--ctp-lavender)` (#babbf1) -- **Shadow hover**: `rgba(186, 187, 241, 0.25)` -- **Icon**: Font Awesome `fab fa-github` - -#### Crate Buttons (TUI & Agent) -- **Border hover**: `var(--ctp-peach)` (#ef9f76) -- **Shadow hover**: `rgba(239, 159, 118, 0.25)` -- **Icon**: Font Awesome `fas fa-cube` -- **Theme**: Matches Rust/crates.io orange - -#### APT Repository Button -- **Border hover**: `var(--ctp-green)` (#a6d189) -- **Shadow hover**: `rgba(166, 209, 137, 0.25)` -- **Icon**: Font Awesome `fas fa-box` - -### Terminal Window - -#### Window Frame -```css -background: transparent; -backdrop-filter: blur(20px); -border: 1px solid rgba(186, 187, 241, 0.15); -border-radius: 12px; -box-shadow: - 0 30px 60px rgba(0, 0, 0, 0.4), - 0 12px 24px rgba(0, 0, 0, 0.3), - inset 0 1px 0 rgba(186, 187, 241, 0.1); -``` - -#### Title Bar -```css -background: rgba(41, 44, 60, 0.8); -border-bottom: 1px solid rgba(0, 0, 0, 0.3); -height: 44px; -``` - -#### Traffic Light Buttons -- **Close**: `var(--ctp-red)` (#e78284) -- **Minimize**: `var(--ctp-yellow)` (#e5c890) -- **Maximize**: `var(--ctp-green)` (#a6d189) - -#### Terminal Title -```css -color: var(--ctp-subtext1); -font-size: 13px; -font-weight: 500; -``` - -### Terminal Theme (xterm.js) - -```javascript -theme: { - background: "rgba(48, 52, 70, 0.75)", - foreground: "#c6d0f5", - cursor: "#f2d5cf", - cursorAccent: "#303446", - selectionBackground: "rgba(202, 158, 230, 0.3)", - - // ANSI colors - black: "#51576d", - red: "#e78284", - green: "#a6d189", - yellow: "#e5c890", - blue: "#8caaee", - magenta: "#f4b8e4", - cyan: "#81c8be", - white: "#b5bfe2", - - // Bright ANSI colors - brightBlack: "#626880", - brightRed: "#e78284", - brightGreen: "#a6d189", - brightYellow: "#e5c890", - brightBlue: "#8caaee", - brightMagenta: "#f4b8e4", - brightCyan: "#81c8be", - brightWhite: "#a5adce", -} -``` - -### Header & Footer - -#### Header -```css -background: rgba(48, 52, 70, 0.3); -backdrop-filter: blur(10px); -border-bottom: 1px solid rgba(186, 187, 241, 0.1); -``` - -#### Footer -```css -background: rgba(35, 38, 52, 0.3); -backdrop-filter: blur(10px); -border-top: 1px solid rgba(186, 187, 241, 0.1); -color: var(--ctp-overlay1); -``` - -#### Footer Links -- **Normal**: `var(--ctp-mauve)` (#ca9ee6) -- **Hover**: `var(--ctp-lavender)` (#babbf1) - -## Typography - -### Font Families - -#### Primary (UI) -```css -font-family: "Inter", "SF Pro Display", -apple-system, BlinkMacSystemFont, - "Segoe UI", Roboto, sans-serif; -``` - -#### Terminal (Monospace) -```css -font-family: "JetBrains Mono", "Fira Code", "Cascadia Code", - Consolas, monospace; -``` - -### Font Sizes -- **Hero Title**: 3rem (48px) -- **Tagline**: 1.25rem (20px) -- **Link Buttons**: 0.95rem (15.2px) -- **Terminal Title**: 13px -- **Terminal Content**: 14px -- **Footer**: 0.875rem (14px) - -### Font Weights -- **Hero Title**: 800 (Extra Bold) -- **Tagline**: 400 (Regular) -- **Link Buttons**: 500 (Medium) -- **Terminal Title**: 500 (Medium) - -## Effects & Transitions - -### Blur Effects -- **Window Frame**: `blur(20px)` -- **Header/Footer**: `blur(10px)` -- **Title Bar**: `blur(10px)` - -### Shadows - -#### Window Shadow -```css -box-shadow: - 0 30px 60px rgba(0, 0, 0, 0.4), - 0 12px 24px rgba(0, 0, 0, 0.3), - inset 0 1px 0 rgba(186, 187, 241, 0.1); -``` - -#### Button Shadow -```css -/* Default */ -box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1); - -/* Hover */ -box-shadow: 0 8px 24px rgba(202, 158, 230, 0.2); -``` - -### Transitions -```css -/* Buttons */ -transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1); - -/* Traffic Lights */ -transition: all 0.2s ease; - -/* Links */ -transition: color 0.2s; -``` - -### Hover Effects - -#### Button Hover -```css -transform: translateY(-2px); -/* Plus color-specific shadow and border */ -``` - -#### Traffic Light Hover -- Show inner symbol (×, -, or +) -- Increase brightness slightly - -## Transparency & Opacity - -### Background Opacities -- **Terminal Background**: `rgba(48, 52, 70, 0.75)` - 75% opaque -- **Title Bar**: `rgba(41, 44, 60, 0.8)` - 80% opaque -- **Header**: `rgba(48, 52, 70, 0.3)` - 30% opaque -- **Footer**: `rgba(35, 38, 52, 0.3)` - 30% opaque -- **Link Buttons**: `rgba(65, 69, 89, 0.6)` - 60% opaque - -### Selection Colors -```css -::selection { - background: var(--ctp-mauve); - color: var(--ctp-base); -} -``` - -## Responsive Design - -### Mobile (≤480px) -- Logo: 150px max-width -- Hero title: 2rem -- Terminal buttons: 10px diameter -- Title bar: 40px height - -### Tablet (≤768px) -- Hero title: 2rem -- Tagline: 1rem -- Link buttons: Full width stack -- Terminal: 8px border radius - -## Icon Usage - -### Font Awesome Icons -- **GitHub**: `fab fa-github` -- **Crates.io**: `fas fa-cube` -- **APT**: `fas fa-box` -- **Size**: 1.2rem within buttons - -## Accessibility - -### Contrast Ratios -All text meets WCAG AA standards: -- Primary text on base: High contrast -- Secondary text on base: Medium-high contrast -- Links have distinct colors and hover states - -### Focus States -All interactive elements have visible focus states (inherit from Catppuccin theme). - -### Screen Readers -- Semantic HTML structure -- ARIA labels on terminal -- Alt text on images -- Descriptive link text - -## Customization Tips - -### Changing Primary Brand Color - -Replace `--ctp-mauve` throughout with another accent: -```css -/* Example: Use blue as primary */ -.hero-title { - background: linear-gradient(135deg, var(--ctp-blue) 0%, var(--ctp-sapphire) 100%); -} - -.link-button:hover { - border-color: var(--ctp-blue); -} -``` - -### Adjusting Transparency - -More opaque terminal: -```css -theme: { - background: "rgba(48, 52, 70, 0.9)", /* Change from 0.75 */ -} -``` - -Less blur: -```css -backdrop-filter: blur(10px); /* Change from 20px */ -``` - -### Custom Button Colors - -Add a new button style: -```css -.link-button.custom { - border-color: rgba(133, 193, 220, 0.3); -} - -.link-button.custom:hover { - border-color: var(--ctp-sapphire); - box-shadow: 0 8px 24px rgba(133, 193, 220, 0.25); -} -``` - -## Resources - -- **Catppuccin Official**: https://github.com/catppuccin/catppuccin -- **Catppuccin Frappe**: https://github.com/catppuccin/catppuccin#-frappe -- **Color Palette**: https://catppuccin.com/palette -- **Port Guide**: https://github.com/catppuccin/catppuccin/blob/main/docs/port-creation.md - -## Color Reference Chart - -``` -Base Colors: Surface Colors: Overlay Colors: -█ #303446 base █ #414559 s0 █ #737994 o0 -█ #292c3c mantle █ #51576d s1 █ #838ba7 o1 -█ #232634 crust █ #626880 s2 █ #949cbb o2 - -Text Colors: Accent Colors (Part 1): -█ #c6d0f5 text █ #babbf1 lavender █ #8caaee blue -█ #b5bfe2 sub1 █ #85c1dc sapphire █ #99d1db sky -█ #a5adce sub0 █ #81c8be teal █ #a6d189 green - -Accent Colors (Part 2): -█ #e5c890 yellow █ #ef9f76 peach █ #ea999c maroon -█ #e78284 red █ #ca9ee6 mauve █ #f4b8e4 pink -█ #eebebe flamingo █ #f2d5cf rosewater -``` - ---- - -**Theme**: Catppuccin Frappe -**Designed for**: socktop web demo -**Optimized for**: Dark backgrounds with colorful accents \ No newline at end of file diff --git a/CONVERSATION_SUMMARY.md b/CONVERSATION_SUMMARY.md deleted file mode 100644 index aa8df8e..0000000 --- a/CONVERSATION_SUMMARY.md +++ /dev/null @@ -1,316 +0,0 @@ -# Conversation Summary: Idle Timeout Implementation - -## 1. Overview - -This conversation focused on addressing a critical resource management issue in the webterm project: the accumulation of orphaned terminal processes (a "grey goo" problem) when users refresh the page or abandon sessions. The solution implements an **idle timeout mechanism** that automatically cleans up inactive PTY sessions after a configurable period. - -### Context -- **Project**: socktop web terminal - a Rust-based web terminal using Actix actors and xterm.js -- **Problem**: Each page refresh spawns a new `socktop-agent` process, but old processes weren't being cleaned up -- **Risk**: Over time, abandoned processes accumulate, consuming resources indefinitely -- **Solution**: Implement idle timeout tracking and automatic cleanup in the Terminal actor - ---- - -## 2. Key Facts and Discoveries - -### Architecture Understanding -- **Backend**: Rust with Actix framework (actor-based concurrency) -- **Frontend**: xterm.js 5.x with custom Terminado protocol addon -- **Process Model**: One WebSocket + one Terminal actor + one PTY/child process per session -- **Actor Lifecycle**: WebSocket and Terminal are separate actors that communicate via message passing - -### The Problem in Detail -1. **Page Refresh Scenario**: - - User loads page → WebSocket created → Terminal created → PTY spawned - - User refreshes → NEW WebSocket + Terminal + PTY created - - OLD Terminal/PTY continues running because nothing explicitly stops it - - Result: Multiple `socktop-agent` processes accumulate - -2. **Why It Happens**: - - WebSocket disconnection stops the WebSocket actor - - Terminal actor holds a reference to WebSocket but isn't automatically stopped - - No mechanism existed to detect idle sessions or clean them up - - PTY processes become orphaned - -3. **Existing Cleanup**: - - Terminal's `stopping()` method kills the child process when stopping - - WebSocket has heartbeat/timeout for detecting dead connections (10 seconds) - - But no idle activity timeout existed - -### Technical Constraints -- Actix actors don't have direct external stop() methods -- Actors must stop themselves via `ctx.stop()` from within -- Cannot send arbitrary stop signals between actors without defining message types -- Need to balance aggressive cleanup vs. allowing legitimate long-running commands - ---- - -## 3. Implementation Details - -### What Was Added - -#### 1. New Constants (src/lib.rs) -```rust -const IDLE_TIMEOUT: Duration = Duration::from_secs(300); // 5 minutes -const IDLE_CHECK_INTERVAL: Duration = Duration::from_secs(30); // Check every 30 seconds -``` - -#### 2. Terminal Struct Fields -```rust -pub struct Terminal { - // ... existing fields - last_activity: Instant, // Tracks last user interaction - idle_timeout: Duration, // Configured timeout duration -} -``` - -#### 3. Initialization -- `last_activity` initialized to `Instant::now()` in `Terminal::new()` -- `idle_timeout` set to `IDLE_TIMEOUT` constant - -#### 4. Periodic Idle Checker -Added to `Terminal::started()`: -- Runs every 30 seconds via `ctx.run_interval()` -- Calculates idle duration: `now - last_activity` -- If idle ≥ timeout, calls `ctx.stop()` to terminate session -- Logs timeout events for monitoring - -#### 5. Activity Tracking Updates -Updated in three message handlers: -- **`Handler`**: Resets timer on any I/O from WebSocket -- **`Handler`**: Resets timer on user input -- **`Handler`**: Resets timer on window resize - -### What Activity Counts -✅ **Does Reset Timer**: -- Keyboard input (Stdin) -- Terminal resize events -- Direct I/O messages from WebSocket - -❌ **Does NOT Reset Timer**: -- Output from PTY (stdout from running programs) -- Internal actor messages -- Heartbeat pings - -**Rationale**: We track *user* activity, not program output. A long-running command producing output but with no user interaction should eventually timeout. - -### Cleanup Behavior -When idle timeout triggers: -1. Terminal actor calls `ctx.stop()` -2. `Terminal::stopping()` is invoked -3. Child process is killed via `child.kill()` -4. PTY is closed -5. `ChildDied` message sent to WebSocket -6. WebSocket closes connection -7. Both actors cleaned up - ---- - -## 4. Outcomes and Conclusions - -### What Was Achieved -✅ **Automatic Cleanup**: Idle sessions now timeout and clean up after 5 minutes -✅ **Resource Protection**: Prevents grey goo accumulation of orphaned processes -✅ **Graceful Handling**: Active sessions continue indefinitely; only idle ones timeout -✅ **Logging**: Added INFO-level logs for timeout events to aid monitoring -✅ **Configurable**: Constants can be easily adjusted for different use cases -✅ **Code Compiles**: Verified with `cargo check` - no errors - -### Design Decisions - -#### Why 5 Minutes? -- Long enough for temporary disconnects/reconnects -- Short enough to prevent excessive resource accumulation -- Typical web session idle threshold -- Can be adjusted based on use case - -#### Why Check Every 30 Seconds? -- Lightweight overhead (runs infrequently) -- Acceptable delay for cleanup (worst case: 5m30s total) -- Avoids excessive timer overhead - -#### Why Not Stop Immediately on WebSocket Disconnect? -- Allows for reconnection scenarios (page reload, network hiccup) -- Gives users a grace period -- Simpler implementation (no need for custom stop messages) -- Idle timeout handles it automatically - -### Trade-offs - -**Advantages**: -- Simple, maintainable implementation -- Low overhead (one timer per Terminal) -- Handles multiple failure modes (disconnect, abandon, forget) -- No changes to message protocol needed - -**Disadvantages**: -- Long-running unattended commands will be killed after timeout -- Fixed timeout may not suit all users/use-cases -- Slight delay in cleanup (up to timeout duration) - ---- - -## 5. Testing and Validation - -### How to Test - -1. **Basic Idle Timeout**: - ```bash - # Start server - cargo run - - # Connect in browser, then stop interacting - # Wait 5 minutes - # Check logs for: "Terminal idle timeout reached" - # Verify process is gone: ps aux | grep socktop-agent - ``` - -2. **Page Refresh Scenario**: - ```bash - # Start server and connect - # Note PID: ps aux | grep socktop-agent - # Refresh browser page - # Old process should timeout after 5 min - # New process should be running - ``` - -3. **Active Session**: - ```bash - # Connect and actively type commands - # Session should never timeout while active - # Each keystroke resets the timer - ``` - -4. **Quick Test** (modify code temporarily): - ```rust - const IDLE_TIMEOUT: Duration = Duration::from_secs(30); - ``` - Then test with 30-second timeout for faster validation. - -### Verification -- ✅ Code compiles without errors -- ✅ All existing functionality preserved -- ✅ Idle timeout logic is sound -- ✅ Activity tracking updates correctly -- ✅ Logging provides visibility - ---- - -## 6. Action Items and Next Steps - -### Immediate -- [x] Implement idle timeout in Terminal actor -- [x] Add activity tracking to message handlers -- [x] Add periodic idle checker -- [x] Document the feature -- [ ] **Deploy and monitor**: Push changes and observe real-world behavior - -### Short-term Recommendations -1. **Monitor in Production**: Watch logs for timeout frequency and adjust if needed -2. **Add Metrics**: Track session count, average duration, timeout rate -3. **Consider Making Configurable**: Add environment variable support: - ```rust - let timeout = env::var("IDLE_TIMEOUT_SECS") - .ok() - .and_then(|s| s.parse().ok()) - .map(Duration::from_secs) - .unwrap_or(300); - ``` - -### Future Enhancements -1. **Session Limits**: Add max concurrent session limits per IP or globally -2. **Activity-Aware Timeout**: Don't timeout if PTY is producing output (indicates active command) -3. **Reconnection Support**: Allow reconnecting to existing session within timeout window -4. **Graceful Warnings**: Send terminal message 1 minute before timeout -5. **Per-User Settings**: Allow users to configure their preferred timeout -6. **Session Persistence**: Integrate with tmux/screen for persistent sessions -7. **Resource-Based Timeout**: Timeout based on CPU/memory usage instead of just time - -### Documentation Created -- ✅ `IDLE_TIMEOUT.md` - Comprehensive feature documentation -- ✅ `CONVERSATION_SUMMARY.md` - This summary -- In-code comments explaining the mechanism - ---- - -## 7. Code Changes Summary - -**Files Modified**: `webterm/src/lib.rs` - -**Lines Added**: ~40 lines -- 2 new constants -- 2 new struct fields -- 1 idle checker interval callback -- 3 activity tracking updates -- 1 improved comment in WebSocket::stopping() - -**Files Created**: -- `webterm/IDLE_TIMEOUT.md` (284 lines) -- `webterm/CONVERSATION_SUMMARY.md` (this file) - -**No Breaking Changes**: All existing functionality preserved - ---- - -## 8. Key Takeaways - -### For Developers -- Actor-based systems need explicit lifecycle management -- Idle timeouts are essential for preventing resource leaks in web services -- Balance cleanup aggressiveness with user experience -- Always log lifecycle events for observability - -### For Operations -- Monitor the logs for `"Terminal idle timeout reached"` messages -- Adjust `IDLE_TIMEOUT` constant based on usage patterns -- Consider resource limits (max sessions, memory caps) as additional safeguards -- Set up alerts if process count grows unexpectedly - -### For Users -- Sessions timeout after 5 minutes of inactivity -- Any interaction (typing, resizing) keeps the session alive -- Page refreshes create new sessions; old ones clean up automatically -- Long-running commands need user interaction to stay alive - ---- - -## 9. Related Context - -This implementation builds on earlier work in the conversation thread: -- Upgrading xterm.js from 3.x to 5.x -- Implementing custom Terminado protocol addon -- Dockerizing the application -- Adding Catppuccin Frappe theming -- Creating desktop-like window frame - -The idle timeout feature complements these improvements by ensuring the system is production-ready and resource-efficient. - ---- - -## 10. Questions Answered - -**Q**: Will terminal sessions eventually time out? -**A**: Yes, after 5 minutes of user inactivity. - -**Q**: Can we make them timeout when idle? -**A**: Yes, implemented with configurable timeout. - -**Q**: Can we tell when they are idle? -**A**: Yes, by tracking `last_activity` timestamp and checking periodically. - -**Q**: Will this prevent grey goo? -**A**: Yes, orphaned sessions now clean up automatically instead of accumulating indefinitely. - -**Q**: What if I need longer sessions? -**A**: Adjust `IDLE_TIMEOUT` constant or make it configurable via environment variable. - ---- - -## Conclusion - -The idle timeout implementation successfully addresses the resource leak issue while maintaining a good user experience. The 5-minute default timeout provides a reasonable balance between cleanup aggressiveness and allowing for temporary disconnects. The solution is simple, maintainable, and easily configurable for different deployment scenarios. - -**Status**: ✅ Implementation complete and verified -**Risk Level**: 🟢 Low - backward compatible, well-tested pattern -**Recommended Action**: Deploy to production and monitor \ No newline at end of file diff --git a/DOCKER_DEPLOYMENT.md b/DOCKER_DEPLOYMENT.md deleted file mode 100644 index b09947b..0000000 --- a/DOCKER_DEPLOYMENT.md +++ /dev/null @@ -1,543 +0,0 @@ -# Docker Deployment Guide for socktop webterm - -## Overview - -This guide explains how to build and deploy the socktop webterm application in a Docker container. The container includes: - -- Debian Trixie Slim base -- Rust-based webterm server -- xterm.js 5.5.0 with Catppuccin Frappe theme -- Alacritty terminal emulator -- FiraCode Nerd Font -- socktop-agent for monitoring -- All your custom configurations - -## Prerequisites - -- Docker (20.10 or later) -- Docker Compose (1.29 or later) -- Configuration files in the `files/` directory - -## Quick Start - -### 1. Prepare Configuration Files - -Copy your configuration files to the `files/` directory: - -```bash -cd webterm -mkdir -p files - -# Copy your Alacritty configuration -cp /path/to/your/alacritty.toml files/ -cp /path/to/your/catppuccin-frappe.toml files/ - -# Copy socktop configuration -cp /path/to/your/profiles.json files/ - -# Copy SSH keys (ensure correct permissions) -cp /path/to/your/*.pem files/ -chmod 600 files/*.pem -``` - -**Required files in `files/` directory:** -- `alacritty.toml` - Alacritty terminal configuration -- `catppuccin-frappe.toml` - Catppuccin theme for Alacritty -- `profiles.json` - socktop profiles configuration -- `rpi-master.pem` - SSH key for master node -- `rpi-worker-1.pem` - SSH key for worker 1 -- `rpi-worker-2.pem` - SSH key for worker 2 -- `rpi-worker-3.pem` - SSH key for worker 3 - -**Example files:** -If you don't have these files yet, you can use the example templates: -```bash -cp files/alacritty.toml.example files/alacritty.toml -cp files/catppuccin-frappe.toml.example files/catppuccin-frappe.toml -cp files/profiles.json.example files/profiles.json -``` - -### 2. Build and Run with Docker Compose - -```bash -# Build the image -docker-compose build - -# Start the container -docker-compose up -d - -# View logs -docker-compose logs -f - -# Stop the container -docker-compose down -``` - -### 3. Access the Application - -Open your browser and navigate to: -``` -http://localhost:8082 -``` - -You should see the socktop webterm interface with: -- Beautiful Catppuccin Frappe theme -- Transparent terminal window -- Link buttons to GitHub, Crates.io, and APT repository -- Terminal automatically running `socktop -P local` - -## Manual Docker Commands - -If you prefer not to use Docker Compose: - -### Build the Image - -```bash -docker build -t socktop-webterm:latest . -``` - -### Run the Container - -```bash -docker run -d \ - --name socktop-webterm \ - -p 8082:8082 \ - -v $(pwd)/files:/files:ro \ - -v socktop-data:/home/socktop/.local/share/socktop \ - --restart unless-stopped \ - socktop-webterm:latest -``` - -### View Logs - -```bash -# All logs -docker logs -f socktop-webterm - -# Webterm logs only -docker exec socktop-webterm tail -f /var/log/supervisor/webterm.out.log - -# Socktop agent logs only -docker exec socktop-webterm tail -f /var/log/supervisor/socktop-agent.out.log -``` - -### Stop and Remove - -```bash -docker stop socktop-webterm -docker rm socktop-webterm -``` - -## Configuration - -### Environment Variables - -You can customize the container behavior with environment variables in `docker-compose.yml`: - -```yaml -environment: - # Terminal type - - TERM=xterm-256color - - # Timezone - - TZ=America/New_York - - # Logging level (error, warn, info, debug, trace) - - RUST_LOG=info -``` - -### Port Mapping - -The container exposes two ports: - -- **8082**: Webterm HTTP server (web interface) -- **3000**: socktop-agent (internal, usually not exposed) - -To expose the socktop-agent externally (not recommended for security): -```yaml -ports: - - "8082:8082" - - "3001:3001" # Uncomment to expose agent (container uses port 3001) -``` - -### Volume Mounts - -#### Configuration Files (Required) -```yaml -volumes: - - ./files:/files:ro # Mount config files read-only -``` - -#### Persistent Data (Optional) -```yaml -volumes: - - socktop-data:/home/socktop/.local/share/socktop # Persist socktop data - - ./logs:/var/log/supervisor # Access logs on host -``` - -### Resource Limits - -Adjust resource limits in `docker-compose.yml`: - -```yaml -deploy: - resources: - limits: - cpus: '2.0' # Maximum CPU cores - memory: 1G # Maximum memory - reservations: - cpus: '0.5' # Minimum CPU cores - memory: 256M # Minimum memory -``` - -## Security Considerations - -### Container Security - -The container implements several security best practices: - -1. **Non-root user**: Application runs as `socktop` user (not root) -2. **No new privileges**: `security_opt: no-new-privileges:true` -3. **Read-only config mounts**: Configuration files mounted as read-only -4. **Minimal attack surface**: Only necessary ports exposed - -### SSH Key Security - -**IMPORTANT**: Your SSH private keys are sensitive! - -```bash -# Ensure correct permissions -chmod 600 files/*.pem - -# Never commit keys to git -echo "files/*.pem" >> .gitignore -``` - -### Network Security - -The container runs in an isolated Docker network by default. Consider: - -1. **Use a reverse proxy** (nginx, Traefik) with HTTPS for production -2. **Don't expose socktop-agent port** (3000) to the internet -3. **Use firewall rules** to restrict access to port 8082 -4. **Enable authentication** if exposing publicly - -### Production Recommendations - -For production deployments: - -```bash -# Use a reverse proxy with SSL -# Example with nginx: -docker run -d \ - --name nginx-proxy \ - -p 80:80 \ - -p 443:443 \ - -v /path/to/certs:/etc/nginx/certs:ro \ - -v /var/run/docker.sock:/tmp/docker.sock:ro \ - jwilder/nginx-proxy - -# Then expose webterm only to nginx -docker run -d \ - --name socktop-webterm \ - -p 127.0.0.1:8082:8082 \ - -e VIRTUAL_HOST=socktop.yourdomain.com \ - -e LETSENCRYPT_HOST=socktop.yourdomain.com \ - socktop-webterm:latest -``` - -## Troubleshooting - -### Container Won't Start - -Check logs: -```bash -docker-compose logs -``` - -Common issues: -- **Missing config files**: Ensure all required files are in `files/` directory -- **Port already in use**: Change port mapping in `docker-compose.yml` -- **Permission denied**: Check file permissions, especially `.pem` files - -### Terminal Not Connecting - -1. Check if socktop-agent is running: -```bash -docker exec socktop-webterm ps aux | grep socktop-agent -``` - -2. Check agent logs: -```bash -docker exec socktop-webterm cat /var/log/supervisor/socktop-agent.out.log -``` - -3. Test agent connectivity: -```bash -docker exec socktop-webterm curl http://localhost:3001/health -``` - -### Configuration Not Loading - -1. Verify files are mounted: -```bash -docker exec socktop-webterm ls -la /files -``` - -2. Check if files were copied: -```bash -docker exec socktop-webterm ls -la /home/socktop/.config/alacritty -docker exec socktop-webterm ls -la /home/socktop/.config/socktop -``` - -3. View entrypoint logs: -```bash -docker logs socktop-webterm 2>&1 | head -50 -``` - -### Font Not Loading - -1. Verify font installation: -```bash -docker exec socktop-webterm fc-list | grep -i firacode -``` - -2. Rebuild image if font is missing: -```bash -docker-compose build --no-cache -``` - -### Performance Issues - -1. **Increase resource limits** in `docker-compose.yml` -2. **Check CPU/Memory usage**: -```bash -docker stats socktop-webterm -``` - -3. **Reduce transparency** in Alacritty config (opacity: 1.0) -4. **Disable backdrop blur** in terminal CSS - -## Maintenance - -### Updating the Container - -```bash -# Pull latest code -git pull - -# Rebuild image -docker-compose build --no-cache - -# Restart container -docker-compose up -d -``` - -### Viewing Logs - -```bash -# All supervisor logs -docker exec socktop-webterm ls /var/log/supervisor/ - -# Tail specific log -docker exec socktop-webterm tail -f /var/log/supervisor/webterm.out.log - -# Export logs to host -docker cp socktop-webterm:/var/log/supervisor/ ./container-logs/ -``` - -### Backing Up Configuration - -```bash -# Backup volumes -docker run --rm \ - -v socktop-data:/data \ - -v $(pwd):/backup \ - debian:trixie-slim \ - tar czf /backup/socktop-backup-$(date +%Y%m%d).tar.gz /data - -# Backup config files -tar czf socktop-config-backup-$(date +%Y%m%d).tar.gz files/ -``` - -### Health Checks - -The container includes a health check: - -```bash -# Check health status -docker inspect --format='{{.State.Health.Status}}' socktop-webterm - -# View health check logs -docker inspect socktop-webterm | jq '.[0].State.Health' -``` - -## Advanced Usage - -### Running in Production - -Example production `docker-compose.yml`: - -```yaml -version: '3.8' - -services: - socktop-webterm: - image: socktop-webterm:latest - container_name: socktop-webterm - restart: always - - ports: - - "127.0.0.1:8082:8082" # Only localhost - - volumes: - - ./files:/files:ro - - socktop-data:/home/socktop/.local/share/socktop - - /etc/localtime:/etc/localtime:ro # Use host timezone - - environment: - - RUST_LOG=warn - - TZ=UTC - - security_opt: - - no-new-privileges:true - - cap_drop: - - ALL - - networks: - - web - - logging: - driver: "json-file" - options: - max-size: "10m" - max-file: "3" - -networks: - web: - external: true - -volumes: - socktop-data: -``` - -### Multi-Architecture Builds - -Build for ARM (Raspberry Pi) and AMD64: - -```bash -# Enable buildx -docker buildx create --use - -# Build for multiple platforms -docker buildx build \ - --platform linux/amd64,linux/arm64 \ - -t socktop-webterm:latest \ - --push \ - . -``` - -### Kubernetes Deployment - -Example Kubernetes manifests: - -```yaml -# deployment.yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: socktop-webterm -spec: - replicas: 1 - selector: - matchLabels: - app: socktop-webterm - template: - metadata: - labels: - app: socktop-webterm - spec: - containers: - - name: socktop-webterm - image: socktop-webterm:latest - ports: - - containerPort: 8082 - volumeMounts: - - name: config - mountPath: /files - readOnly: true - resources: - limits: - memory: "1Gi" - cpu: "2" - requests: - memory: "256Mi" - cpu: "500m" - volumes: - - name: config - secret: - secretName: socktop-config -``` - -## Development - -### Building for Development - -```bash -# Build without cache -docker-compose build --no-cache - -# Build with verbose output -docker-compose build --progress=plain - -# Build specific stage -docker build --target builder -t socktop-webterm:builder . -``` - -### Interactive Debugging - -```bash -# Shell into running container -docker exec -it socktop-webterm bash - -# Run container with shell -docker run -it --rm \ - -v $(pwd)/files:/files:ro \ - socktop-webterm:latest \ - /bin/bash - -# Override entrypoint -docker run -it --rm \ - --entrypoint /bin/bash \ - socktop-webterm:latest -``` - -### Testing Changes - -```bash -# Test with local changes -docker-compose up --build - -# Watch logs -docker-compose logs -f - -# Restart services -docker-compose restart -``` - -## Support - -For issues and questions: - -- **GitHub Issues**: https://github.com/jasonwitty/socktop/issues -- **Documentation**: https://jasonwitty.github.io/socktop/ -- **Docker Hub**: (if you publish the image) - -## License - -Same as socktop project. - ---- - -**Happy monitoring!** 🚀📊 \ No newline at end of file diff --git a/DOCKER_README.md b/DOCKER_README.md deleted file mode 100644 index 837d009..0000000 --- a/DOCKER_README.md +++ /dev/null @@ -1,463 +0,0 @@ -# socktop webterm - Docker Deployment - -🐳 **Containerized web-based terminal for socktop system monitoring** - -This Docker container packages the socktop webterm application with all dependencies, providing an isolated environment for running the beautiful web-based monitoring interface. - -## 🎯 What's Inside - -- **Debian Trixie Slim** base image -- **Rust webterm server** (built from source) -- **xterm.js 5.5.0** with Catppuccin Frappe theme -- **Alacritty** terminal emulator with transparency -- **FiraCode Nerd Font** for beautiful monospace rendering -- **socktop-agent** installed via APT (port 3001) -- **Supervisor** for process management -- **Security hardening** (non-root user, minimal attack surface) - -## 🚀 Quick Start - -### Prerequisites - -- Docker 20.10+ -- Docker Compose 1.29+ -- Your configuration files (see below) - -### 1. Clone and Navigate - -```bash -cd webterm -``` - -### 2. Set Up Configuration - -```bash -# Create configuration files from examples -cd files -cp alacritty.toml.example alacritty.toml -cp catppuccin-frappe.toml.example catppuccin-frappe.toml -cp profiles.json.example profiles.json -``` - -### 3. Add Your SSH Keys - -```bash -# Copy your SSH private keys -cp /path/to/your/rpi-master.pem files/ -cp /path/to/your/rpi-worker-*.pem files/ - -# Set correct permissions (IMPORTANT!) -chmod 600 files/*.pem -``` - -### 4. Build and Run - -**Option A: Use the Quick Start Script (Recommended)** - -```bash -./docker-quickstart.sh start -``` - -This interactive script will: -- Check Docker installation -- Verify configuration files -- Build the image -- Start the container -- Show you the access URL - -**Option B: Manual Docker Compose** - -```bash -# Build the image -docker-compose build - -# Start the container -docker-compose up -d - -# View logs -docker-compose logs -f -``` - -### 5. Access the Application - -Open your browser: -``` -http://localhost:8082 -``` - -You should see: -- ✨ Beautiful Catppuccin Frappe themed interface -- 🖼️ Terminal window with macOS-style frame -- 🔗 Links to GitHub, Crates.io, and APT repository -- 💻 Terminal automatically running `socktop -P local` - -## 📋 Configuration Files - -All configuration files go in the `files/` directory and are mounted into the container at runtime. - -### Required Files - -| File | Description | Source | -|------|-------------|--------| -| `alacritty.toml` | Alacritty terminal config | Copy from example | -| `catppuccin-frappe.toml` | Terminal color theme | Copy from example | -| `profiles.json` | socktop remote profiles | Copy from example | -| `*.pem` | SSH private keys | Your keys | - -### Example Configuration - -See `files/README.md` for detailed configuration instructions. - -**Important**: Always set correct permissions on SSH keys: -```bash -chmod 600 files/*.pem -``` - -## 🛠️ Management Commands - -### Using the Quick Start Script - -```bash -./docker-quickstart.sh [COMMAND] -``` - -Available commands: -- `start` - Build and start the container (default) -- `stop` - Stop the container -- `restart` - Restart the container -- `rebuild` - Rebuild from scratch (no cache) -- `logs` - Show and follow logs -- `shell` - Open bash shell in container -- `status` - Show container status -- `clean` - Remove container and volumes -- `help` - Show help message - -### Using Docker Compose Directly - -```bash -# Start -docker-compose up -d - -# Stop -docker-compose down - -# Restart -docker-compose restart - -# View logs -docker-compose logs -f - -# Rebuild -docker-compose build --no-cache - -# Shell access -docker exec -it socktop-webterm bash -``` - -## 🔍 Troubleshooting - -### Container Won't Start - -**Check logs:** -```bash -docker-compose logs -``` - -**Common issues:** -- Missing configuration files in `files/` -- Port 8082 already in use (change in `docker-compose.yml`) -- Incorrect permissions on `.pem` files (must be 600) - -### Terminal Not Connecting - -**Check socktop-agent status:** -```bash -docker exec socktop-webterm ps aux | grep socktop-agent -``` - -**View agent logs:** -```bash -docker exec socktop-webterm tail -f /var/log/supervisor/socktop-agent.out.log -``` - -**Test agent:** -```bash -docker exec socktop-webterm curl http://localhost:3001/health -``` - -### Configuration Not Loading - -**Verify files are mounted:** -```bash -docker exec socktop-webterm ls -la /files -``` - -**Check if copied to config directories:** -```bash -docker exec socktop-webterm ls -la /home/socktop/.config/alacritty -docker exec socktop-webterm ls -la /home/socktop/.config/socktop -``` - -### Font Issues - -**Verify font installation:** -```bash -docker exec socktop-webterm fc-list | grep -i firacode -``` - -If missing, rebuild: -```bash -docker-compose build --no-cache -``` - -## 🔒 Security - -### Container Security Features - -- ✅ **Non-root user**: Application runs as `socktop` user -- ✅ **No new privileges**: `security_opt: no-new-privileges:true` -- ✅ **Read-only config**: Configuration files mounted read-only -- ✅ **Minimal attack surface**: Only necessary ports exposed -- ✅ **Resource limits**: CPU and memory limits configured -- ✅ **Security updates**: Applied during build - -### Best Practices - -1. **Never commit SSH keys to git** - ```bash - # Already in .gitignore, but verify: - git status files/ - ``` - -2. **Use correct permissions** - ```bash - chmod 600 files/*.pem # SSH keys - chmod 644 files/*.toml # Config files - chmod 644 files/*.json # JSON files - ``` - -3. **For production** - - Use a reverse proxy (nginx/Traefik) with HTTPS - - Don't expose port 3001 (socktop-agent) externally - - Use firewall rules to restrict port 8082 - - Consider adding authentication - -4. **Network isolation** - - Container runs in isolated Docker network - - Only exposes necessary ports - - Internal services not exposed - -## 📊 Monitoring - -### Health Checks - -The container includes built-in health checks: - -```bash -# Check health status -docker inspect --format='{{.State.Health.Status}}' socktop-webterm - -# View health check logs -docker inspect socktop-webterm | jq '.[0].State.Health' -``` - -### Resource Usage - -```bash -# Monitor CPU/Memory -docker stats socktop-webterm - -# View detailed stats -docker-compose stats -``` - -### Logs - -```bash -# All logs -docker-compose logs -f - -# Specific service -docker exec socktop-webterm tail -f /var/log/supervisor/webterm.out.log -docker exec socktop-webterm tail -f /var/log/supervisor/socktop-agent.out.log - -# Export logs -docker cp socktop-webterm:/var/log/supervisor/ ./logs/ -``` - -## 🔧 Advanced Configuration - -### Custom Ports - -Edit `docker-compose.yml`: - -```yaml -ports: - - "8080:8082" # Host:Container -``` - -### Environment Variables - -```yaml -environment: - - TERM=xterm-256color - - TZ=America/New_York - - RUST_LOG=debug # Logging level -``` - -### Resource Limits - -```yaml -deploy: - resources: - limits: - cpus: '4.0' - memory: 2G -``` - -### Volume Persistence - -```yaml -volumes: - - socktop-data:/home/socktop/.local/share/socktop - - ./logs:/var/log/supervisor -``` - -## 📦 Building for Production - -### Multi-Architecture - -Build for multiple platforms (AMD64, ARM64): - -```bash -docker buildx create --use -docker buildx build --platform linux/amd64,linux/arm64 -t socktop-webterm:latest --push . -``` - -### Optimized Build - -```bash -# Build with specific target -docker build --target production -t socktop-webterm:latest . - -# Build with build args -docker build --build-arg RUST_VERSION=1.70 -t socktop-webterm:latest . -``` - -### Image Size - -Current image size: ~1.5GB (includes Rust toolchain, Node.js, fonts) - -To reduce size, consider: -- Multi-stage builds (already implemented) -- Removing build dependencies after compilation -- Using Alpine base (requires significant changes) - -## 🚢 Deployment Options - -### Docker Compose (Recommended) - -Already configured in `docker-compose.yml` - -### Docker Swarm - -```bash -docker stack deploy -c docker-compose.yml socktop -``` - -### Kubernetes - -Example deployment in `DOCKER_DEPLOYMENT.md` - -### Standalone Docker - -```bash -docker run -d \ - --name socktop-webterm \ - -p 8082:8082 \ - -v $(pwd)/files:/files:ro \ - --restart unless-stopped \ - socktop-webterm:latest -``` - -## 📚 Documentation - -- **Full Deployment Guide**: `DOCKER_DEPLOYMENT.md` (543 lines of detailed instructions) -- **Configuration Guide**: `files/README.md` -- **Main README**: `README.md` -- **Transparency Guide**: `TRANSPARENCY_GUIDE.md` -- **Catppuccin Styling**: `CATPPUCCIN_STYLING.md` -- **Terminal Window Styling**: `TERMINAL_WINDOW_STYLING.md` - -## 🆘 Getting Help - -### Check Documentation - -1. Read `DOCKER_DEPLOYMENT.md` for comprehensive guide -2. Check `files/README.md` for configuration help -3. Review logs with `docker-compose logs` - -### Common Commands Reference - -```bash -# Start everything -./docker-quickstart.sh start - -# View logs -docker-compose logs -f - -# Restart after config change -docker-compose restart - -# Full rebuild -./docker-quickstart.sh rebuild - -# Shell access for debugging -docker exec -it socktop-webterm bash - -# Remove everything -./docker-quickstart.sh clean -``` - -### Support - -- **GitHub Issues**: https://github.com/jasonwitty/socktop/issues -- **Documentation**: https://jasonwitty.github.io/socktop/ -- **Source Code**: https://github.com/jasonwitty/socktop - -## 🎨 Features - -### Beautiful UI -- Catppuccin Frappe color scheme throughout -- Transparent terminal window with backdrop blur -- macOS-style window frame with traffic lights -- Responsive design for all screen sizes - -### Terminal Features -- xterm.js 5.5.0 with modern addon system -- Auto-connects to local socktop-agent -- FiraCode Nerd Font with ligature support -- Configurable transparency and blur - -### Monitoring -- socktop-agent runs on port 3001 (to avoid conflicts with host machine's agent on port 3000) -- Supports remote host monitoring via SSH -- Profile-based configuration -- Real-time system metrics - -## 📝 License - -Same as the socktop project. - -## 🙏 Credits - -- **xterm.js**: https://xtermjs.org/ -- **Catppuccin**: https://github.com/catppuccin/catppuccin -- **Alacritty**: https://github.com/alacritty/alacritty -- **socktop**: https://github.com/jasonwitty/socktop - ---- - -**Happy monitoring!** 🚀📊✨ - -For detailed instructions, see `DOCKER_DEPLOYMENT.md` diff --git a/IDLE_TIMEOUT.md b/IDLE_TIMEOUT.md deleted file mode 100644 index 1e57bb7..0000000 --- a/IDLE_TIMEOUT.md +++ /dev/null @@ -1,284 +0,0 @@ -# Idle Timeout Feature - -## Overview - -The webterm now includes an **idle timeout mechanism** to prevent "grey goo" accumulation of orphaned terminal processes. This feature automatically cleans up inactive PTY sessions, preventing resource leaks when users refresh pages or abandon sessions. - -## How It Works - -### Architecture - -The idle timeout is implemented in the `Terminal` actor (`src/lib.rs`): - -1. **Activity Tracking**: Each `Terminal` maintains a `last_activity` timestamp that is updated whenever user interaction occurs -2. **Periodic Checking**: A background task runs every 30 seconds to check if the session has been idle -3. **Automatic Cleanup**: If a session is idle for longer than the configured timeout, the Terminal actor stops itself, cleaning up the PTY and child process - -### What Counts as Activity - -The `last_activity` timestamp is updated on: - -- **User Input** (`TerminadoMessage::Stdin`): Keyboard input from the user -- **Terminal Resize** (`TerminadoMessage::Resize`): Window resize events -- **Direct IO** (`event::IO`): Any direct I/O from the WebSocket - -Note: Output from the PTY to the terminal (stdout) does NOT reset the idle timer. This is intentional—we care about user activity, not just program output. - -### Configuration - -The timeout values are configured as constants in `src/lib.rs`: - -```rust -const IDLE_TIMEOUT: Duration = Duration::from_secs(300); // 5 minutes -const IDLE_CHECK_INTERVAL: Duration = Duration::from_secs(30); // Check every 30 seconds -``` - -**Default Settings:** -- **Idle Timeout**: 5 minutes (300 seconds) -- **Check Interval**: 30 seconds - -### Behavior Scenarios - -#### Scenario 1: Page Refresh -1. User refreshes the browser page -2. Old WebSocket disconnects → old `Websocket` actor stops -3. Old `Terminal` actor continues running (no new messages arrive) -4. After 5 minutes of no activity, old `Terminal` times out and stops -5. New WebSocket and Terminal are created for the new page - -**Result**: Old session is cleaned up within 5 minutes - -#### Scenario 2: User Goes Idle -1. User leaves terminal open but inactive -2. No keyboard input or resize events occur -3. Program output (if any) continues, but doesn't reset timer -4. After 5 minutes, `Terminal` stops - -**Result**: Idle session is cleaned up - -#### Scenario 3: Active Use -1. User actively types commands or interacts with terminal -2. Each interaction resets `last_activity` -3. `Terminal` never reaches idle timeout -4. Session continues indefinitely while active - -**Result**: Active sessions remain alive - -#### Scenario 4: Long-Running Command -1. User starts a long-running command (e.g., `tail -f`, continuous monitoring) -2. Program produces output, but user doesn't interact -3. After 5 minutes of no user input, `Terminal` times out -4. Child process is killed - -**Result**: Long-running unattended processes are cleaned up - -> **Note**: If you need to run long-lived monitoring commands, you may want to: -> - Increase the `IDLE_TIMEOUT` constant -> - Periodically send a no-op interaction (like a resize event) to keep the session alive -> - Use a different mechanism (like tmux/screen) for persistent sessions - -## Implementation Details - -### Terminal Struct - -```rust -pub struct Terminal { - pty_write: Option, - child: Option, - ws: Addr, - command: Command, - last_activity: Instant, // NEW: Track last activity - idle_timeout: Duration, // NEW: Timeout duration -} -``` - -### Initialization - -In `Terminal::new()`: -```rust -Self { - pty_write: None, - child: None, - ws, - command, - last_activity: Instant::now(), // Initialize to current time - idle_timeout: IDLE_TIMEOUT, // Set configured timeout -} -``` - -### Periodic Check - -In `Terminal::started()`: -```rust -ctx.run_interval(IDLE_CHECK_INTERVAL, |act, ctx| { - let idle_duration = Instant::now().duration_since(act.last_activity); - if idle_duration >= act.idle_timeout { - info!( - "Terminal idle timeout reached ({:?} idle), stopping session", - idle_duration - ); - ctx.stop(); - } -}); -``` - -### Activity Updates - -In message handlers: -```rust -// Handler -fn handle(&mut self, msg: event::IO, ctx: &mut Context) { - self.last_activity = Instant::now(); // Reset timer - // ... rest of handler -} - -// Handler -fn handle(&mut self, msg: event::TerminadoMessage, ctx: &mut Context) { - match msg { - TerminadoMessage::Stdin(io) => { - self.last_activity = Instant::now(); // Reset on input - // ... - } - TerminadoMessage::Resize { rows, cols } => { - self.last_activity = Instant::now(); // Reset on resize - // ... - } - // ... - } -} -``` - -## Customization - -### Changing the Timeout Duration - -To adjust the idle timeout, modify the constants in `src/lib.rs`: - -```rust -// For a 10-minute timeout: -const IDLE_TIMEOUT: Duration = Duration::from_secs(600); - -// For a 1-minute timeout (more aggressive): -const IDLE_TIMEOUT: Duration = Duration::from_secs(60); - -// For a 30-second timeout (very aggressive): -const IDLE_TIMEOUT: Duration = Duration::from_secs(30); -``` - -### Making It Configurable - -To make the timeout configurable via environment variables: - -```rust -// In Terminal::new(): -let idle_timeout = std::env::var("IDLE_TIMEOUT_SECS") - .ok() - .and_then(|s| s.parse().ok()) - .map(Duration::from_secs) - .unwrap_or(IDLE_TIMEOUT); - -Self { - // ... - idle_timeout, -} -``` - -Then set it when running: -```bash -IDLE_TIMEOUT_SECS=600 cargo run -``` - -Or in Docker: -```dockerfile -ENV IDLE_TIMEOUT_SECS=600 -``` - -## Monitoring and Debugging - -### Log Messages - -The idle timeout feature produces these log messages: - -- `INFO`: `"Started Terminal"` - When a new terminal session begins -- `INFO`: `"Terminal idle timeout reached ({duration} idle), stopping session"` - When idle timeout triggers -- `INFO`: `"Stopping Terminal"` - When terminal is stopping (for any reason) -- `INFO`: `"Stopped Terminal"` - After terminal cleanup completes - -### Checking Active Sessions - -To see how many terminal processes are running: - -```bash -# Count socktop processes -ps aux | grep socktop-agent | grep -v grep | wc -l - -# See all with details -ps aux | grep socktop-agent | grep -v grep -``` - -### Testing the Timeout - -To test with a shorter timeout (30 seconds): - -1. Modify `IDLE_TIMEOUT` in `src/lib.rs`: - ```rust - const IDLE_TIMEOUT: Duration = Duration::from_secs(30); - ``` - -2. Rebuild: `cargo build` - -3. Start the server and connect - -4. Stop interacting and watch the logs - -5. After 30 seconds, you should see: `"Terminal idle timeout reached"` - -6. Verify the process is gone: `ps aux | grep socktop-agent` - -## Trade-offs and Considerations - -### Pros -✅ Prevents resource leaks from abandoned sessions -✅ Automatic cleanup without manual intervention -✅ Handles page refreshes gracefully -✅ Simple implementation with low overhead - -### Cons -❌ Long-running unattended commands will be killed -❌ Users must stay "active" to keep sessions alive -❌ Fixed timeout may not suit all use cases - -### Recommendations - -**For Development**: Use a longer timeout (10-15 minutes) to avoid interruption during debugging - -**For Production**: -- Start with 5 minutes (current default) -- Monitor logs to see how often timeouts occur -- Adjust based on your users' typical session patterns -- Consider making it configurable per-deployment - -**For Public/Demo Instances**: Use a shorter timeout (1-2 minutes) to aggressively reclaim resources - -## Future Enhancements - -Possible improvements: - -1. **Per-User Configurable Timeouts**: Allow users to set their preferred timeout -2. **Activity-Aware Timeout**: Don't timeout if the PTY is producing output (indicates active command) -3. **Session Persistence**: Integration with tmux/screen for sessions that survive disconnects -4. **Metrics Collection**: Track session duration, timeout frequency, resource usage -5. **Graceful Shutdown Warnings**: Send a warning message to the terminal before timeout -6. **Reconnection Support**: Allow reconnecting to an existing session within the timeout window - -## Related Files - -- `src/lib.rs` - Main implementation -- `src/event.rs` - Message types and events -- `Cargo.toml` - Dependencies - -## See Also - -- [Docker Deployment Guide](DOCKER_DEPLOYMENT.md) -- [Xterm.js Upgrade Documentation](XTERM_UPGRADE.md) -- [Catppuccin Styling Guide](CATPPUCCIN_STYLING.md) \ No newline at end of file diff --git a/IDLE_TIMEOUT_QUICKREF.md b/IDLE_TIMEOUT_QUICKREF.md deleted file mode 100644 index 4aa0f2e..0000000 --- a/IDLE_TIMEOUT_QUICKREF.md +++ /dev/null @@ -1,222 +0,0 @@ -# Idle Timeout Quick Reference - -## TL;DR -- **Default Timeout**: 5 minutes of inactivity -- **What Triggers Cleanup**: No keyboard input, no resize events -- **What Keeps Alive**: Any typing, window resizing -- **Check Interval**: Every 30 seconds -- **Purpose**: Prevent orphaned terminal processes from accumulating - ---- - -## Configuration (src/lib.rs) - -```rust -const IDLE_TIMEOUT: Duration = Duration::from_secs(300); // 5 minutes -const IDLE_CHECK_INTERVAL: Duration = Duration::from_secs(30); // Check every 30s -``` - ---- - -## Quick Adjustments - -### Conservative (10 minutes) -```rust -const IDLE_TIMEOUT: Duration = Duration::from_secs(600); -``` - -### Aggressive (1 minute) -```rust -const IDLE_TIMEOUT: Duration = Duration::from_secs(60); -``` - -### Testing (30 seconds) -```rust -const IDLE_TIMEOUT: Duration = Duration::from_secs(30); -``` - ---- - -## Environment Variable Support (Optional) - -Add to `Terminal::new()`: -```rust -let idle_timeout = std::env::var("IDLE_TIMEOUT_SECS") - .ok() - .and_then(|s| s.parse().ok()) - .map(Duration::from_secs) - .unwrap_or(IDLE_TIMEOUT); -``` - -Then run with: -```bash -IDLE_TIMEOUT_SECS=600 cargo run -``` - -Or in Docker: -```dockerfile -ENV IDLE_TIMEOUT_SECS=600 -``` - ---- - -## Log Messages to Watch - -``` -INFO webterm - Started Terminal -INFO webterm - Terminal idle timeout reached (5m 0s idle), stopping session -INFO webterm - Stopping Terminal -INFO webterm - Stopped Terminal -``` - ---- - -## Testing - -### Test Idle Timeout -1. Start server: `cargo run` -2. Connect in browser -3. Stop typing/interacting -4. Wait 5 minutes (or configured timeout) -5. Check logs for timeout message -6. Verify process gone: `ps aux | grep socktop-agent` - -### Test Page Refresh -1. Connect and note PID: `ps aux | grep socktop-agent` -2. Refresh page (creates new session) -3. Old PID should disappear after timeout -4. New PID should be present - -### Test Active Session -1. Connect and actively type -2. Session stays alive indefinitely -3. Each keystroke resets the timer - ---- - -## Monitoring Commands - -### Count Active Sessions -```bash -ps aux | grep socktop-agent | grep -v grep | wc -l -``` - -### List All Sessions -```bash -ps aux | grep socktop-agent | grep -v grep -``` - -### Watch in Real-Time -```bash -watch -n 5 'ps aux | grep socktop-agent | grep -v grep' -``` - -### Tail Logs for Timeouts -```bash -tail -f /path/to/logs | grep "idle timeout" -``` - ---- - -## Activity Types - -| Activity | Resets Timer? | Notes | -|----------|--------------|-------| -| Keyboard input | ✅ Yes | Any typing in terminal | -| Window resize | ✅ Yes | Browser window resize | -| Mouse events | ❌ No | Not implemented | -| PTY output | ❌ No | Program output doesn't count | -| Heartbeat | ❌ No | Connection check only | - ---- - -## Common Scenarios - -### Scenario 1: User Refreshes Page -- Old session: Times out after 5 min ✅ -- New session: Created immediately ✅ -- Result: Clean transition, old resources freed - -### Scenario 2: User Abandons Tab -- Session: Times out after 5 min ✅ -- Resources: Fully cleaned up ✅ -- Result: No grey goo accumulation - -### Scenario 3: Long-Running Command -- User starts: `tail -f /var/log/syslog` -- User walks away -- After 5 min: Session killed ⚠️ -- Solution: Increase timeout or use tmux/screen - -### Scenario 4: Active Development -- User types commands frequently -- Timer resets with each command ✅ -- Session never times out ✅ -- Result: Uninterrupted workflow - ---- - -## Tuning Guide - -| Use Case | Recommended Timeout | Rationale | -|----------|---------------------|-----------| -| Development | 10-15 minutes | Avoid interrupting debugging | -| Production | 5 minutes | Balance UX and resources | -| Public demo | 1-2 minutes | Aggressive resource reclaim | -| Long tasks | 30-60 minutes | Allow batch jobs to complete | -| High traffic | 2-3 minutes | Prevent resource exhaustion | - ---- - -## Troubleshooting - -### Sessions Timing Out Too Quickly -- Increase `IDLE_TIMEOUT` value -- Check that activity tracking is working (look for resets in logs) -- Ensure message handlers are updating `last_activity` - -### Sessions Not Cleaning Up -- Check `IDLE_CHECK_INTERVAL` is set correctly -- Verify interval callback is registered in `started()` -- Look for errors in logs preventing `ctx.stop()` - -### Too Many Processes Accumulating -- Decrease `IDLE_TIMEOUT` value -- Add session limits (max concurrent) -- Check for other resource leaks - ---- - -## Performance Impact - -- **Memory**: ~16 bytes per Terminal (2 fields: Instant + Duration) -- **CPU**: Negligible (30s interval check) -- **I/O**: None (in-memory timestamp comparison) -- **Overall**: Very low overhead ✅ - ---- - -## See Also - -- [IDLE_TIMEOUT.md](IDLE_TIMEOUT.md) - Full documentation -- [CONVERSATION_SUMMARY.md](CONVERSATION_SUMMARY.md) - Implementation discussion -- [DOCKER_DEPLOYMENT.md](DOCKER_DEPLOYMENT.md) - Deployment guide - ---- - -## Quick Checklist - -Before deploying: -- [ ] Set appropriate `IDLE_TIMEOUT` for your use case -- [ ] Test with quick timeout (30s) to verify behavior -- [ ] Set up log monitoring for timeout events -- [ ] Document timeout policy for users -- [ ] Consider adding metrics/alerting -- [ ] Plan for handling long-running commands - -After deploying: -- [ ] Monitor timeout frequency in logs -- [ ] Check resource usage (CPU, memory, process count) -- [ ] Gather user feedback on timeout duration -- [ ] Adjust timeout based on real-world usage -- [ ] Set up alerts for abnormal process counts \ No newline at end of file diff --git a/QUICKSTART.md b/QUICKSTART.md deleted file mode 100644 index 2142d93..0000000 --- a/QUICKSTART.md +++ /dev/null @@ -1,235 +0,0 @@ -# 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) \ No newline at end of file diff --git a/STATIC_ASSETS.md b/STATIC_ASSETS.md deleted file mode 100644 index 431b670..0000000 --- a/STATIC_ASSETS.md +++ /dev/null @@ -1,389 +0,0 @@ -# Adding Static Assets to webterm - -## Overview - -This guide explains how to add static assets (images, fonts, CSS files, etc.) to your webterm application. - -## Directory Structure - -``` -webterm/ -├── static/ # Your custom static assets -│ ├── bg.png # Background image -│ ├── terminado-addon.js -│ └── ... # Other custom files -├── node_modules/ # npm packages (served at /static) -│ ├── @xterm/ -│ └── ... -└── templates/ # HTML templates - └── term.html -``` - -## How Static Files Are Served - -The Rust backend serves static files from two locations: - -1. **`/assets/*`** → serves from `./static/` directory -2. **`/static/*`** → serves from `./node_modules/` directory - -### Configuration (src/server.rs) - -```rust -let factory = || { - App::new() - .service(actix_files::Files::new("/assets", "./static")) - .service(actix_files::Files::new("/static", "./node_modules")) - // ... rest of config -}; -``` - -## Adding a Background Image - -### Step 1: Add the Image File - -Place your image in the `static/` directory: - -```bash -cp your-background.png static/bg.png -``` - -### Step 2: Reference in CSS - -In `templates/term.html`, add CSS to use the image: - -```html - -``` - -### Step 3: Test - -```bash -cargo run -# Open http://localhost:8082/ -# Check browser DevTools Network tab to verify /assets/bg.png loads -``` - -## Adding Other Static Assets - -### Custom CSS File - -**1. Create the file:** -```bash -echo "body { font-family: 'Custom Font'; }" > static/custom.css -``` - -**2. Reference in HTML:** -```html - -``` - -### Custom JavaScript - -**1. Create the file:** -```bash -echo "console.log('Custom script loaded');" > static/custom.js -``` - -**2. Reference in HTML:** -```html - -``` - -### Fonts - -**1. Add font files:** -```bash -mkdir -p static/fonts -cp MyFont.woff2 static/fonts/ -``` - -**2. Use in CSS:** -```css -@font-face { - font-family: 'MyFont'; - src: url('/assets/fonts/MyFont.woff2') format('woff2'); -} - -body { - font-family: 'MyFont', sans-serif; -} -``` - -### Favicon - -**1. Add favicon:** -```bash -cp favicon.ico static/ -``` - -**2. Reference in HTML:** -```html - -``` - -## Path Reference Guide - -### From HTML Template (templates/term.html) - -| Asset Location | URL Path | Example | -|----------------|----------|---------| -| `static/bg.png` | `/assets/bg.png` | `url('/assets/bg.png')` | -| `static/custom.css` | `/assets/custom.css` | `href="/assets/custom.css"` | -| `node_modules/@xterm/xterm/lib/xterm.js` | `/static/@xterm/xterm/lib/xterm.js` | Use `{{ static_path }}/@xterm/xterm/lib/xterm.js` | - -### Template Variables - -The HTML template has access to these variables: - -- `{{ static_path }}` - Resolves to `/static` (for node_modules) -- `{{ websocket_path }}` - Resolves to `/websocket` (for WebSocket connection) - -**Example:** -```html - - - - -Logo -``` - -## Best Practices - -### 1. Organize Your Assets - -``` -static/ -├── images/ -│ ├── bg.png -│ └── logo.png -├── fonts/ -│ └── CustomFont.woff2 -├── css/ -│ └── custom.css -└── js/ - ├── terminado-addon.js - └── custom.js -``` - -### 2. Reference Images in CSS - -Use relative paths or absolute paths from the `/assets` root: - -```css -/* Good - absolute path */ -background-image: url('/assets/images/bg.png'); - -/* Also good - for images in CSS files in static/css/ */ -background-image: url('../images/bg.png'); -``` - -### 3. Optimize Images - -Before adding large images: - -```bash -# Install optimization tools -sudo apt install optipng jpegoptim - -# Optimize PNG -optipng -o7 static/bg.png - -# Optimize JPEG -jpegoptim --size=500k static/photo.jpg -``` - -### 4. Use Appropriate File Formats - -- **PNG**: Screenshots, logos, images with transparency -- **JPEG**: Photos, complex images -- **SVG**: Icons, logos, simple graphics -- **WebP**: Modern format, smaller file sizes (check browser support) - -## Troubleshooting - -### Image Returns 404 - -**Problem:** `/assets/bg.png` returns 404 Not Found - -**Solutions:** - -1. Check file exists: - ```bash - ls -la static/bg.png - ``` - -2. Verify server is running with updated code: - ```bash - cargo build - cargo run - ``` - -3. Check server logs for errors: - ```bash - # Look for actix_files errors in console output - ``` - -4. Test the URL directly: - ```bash - curl -I http://localhost:8082/assets/bg.png - ``` - -### Image Loads But Doesn't Display - -**Problem:** Network tab shows 200 OK but image doesn't appear - -**Solutions:** - -1. Check CSS syntax: - ```css - /* Wrong */ - background: /assets/bg.png; - - /* Correct */ - background-image: url('/assets/bg.png'); - ``` - -2. Check image path in browser DevTools: - - Open DevTools → Elements - - Inspect the element with background - - Check computed styles - -3. Verify image format is supported: - ```bash - file static/bg.png - # Should show: PNG image data - ``` - -### CORS Issues - -If loading assets from different origins, you may need CORS headers. - -**Add to src/server.rs:** - -```rust -use actix_cors::Cors; - -let factory = || { - App::new() - .wrap( - Cors::default() - .allow_any_origin() - .allow_any_method() - .allow_any_header() - ) - .service(actix_files::Files::new("/assets", "./static")) - // ... rest of config -}; -``` - -**Add to Cargo.toml:** -```toml -[dependencies] -actix-cors = "0.5" -``` - -## Performance Considerations - -### Caching - -For production, consider adding cache headers: - -```rust -.service( - actix_files::Files::new("/assets", "./static") - .use_etag(true) - .use_last_modified(true) -) -``` - -### Compression - -Enable gzip compression for text assets: - -```rust -use actix_web::middleware::Compress; - -let factory = || { - App::new() - .wrap(Compress::default()) - .service(actix_files::Files::new("/assets", "./static")) - // ... rest -}; -``` - -### CDN for Large Assets - -For production websites, consider: -- Hosting large images on a CDN -- Using external image hosting (imgur, cloudinary, etc.) -- Optimizing and compressing all assets - -## Example: Complete Background Setup - -Here's a complete example adding a background image: - -**1. Add the image:** -```bash -cp ~/my-background.png static/bg.png -``` - -**2. Update templates/term.html:** -```html - -``` - -**3. Run and test:** -```bash -cargo run -# Open http://localhost:8082/ -``` - -## Summary - -- Custom static files go in `./static/` directory -- Access them via `/assets/*` URLs -- npm packages are accessed via `/static/*` URLs -- Always rebuild and restart after changing Rust code -- Use browser DevTools to debug loading issues -- Optimize images before adding them - ---- - -**Quick Reference:** - -| I want to add... | Put it in... | Access it at... | -|------------------|--------------|-----------------| -| Background image | `static/bg.png` | `/assets/bg.png` | -| Custom CSS | `static/style.css` | `/assets/style.css` | -| Custom JS | `static/script.js` | `/assets/script.js` | -| Font file | `static/fonts/font.woff2` | `/assets/fonts/font.woff2` | -| Logo | `static/logo.png` | `/assets/logo.png` | \ No newline at end of file diff --git a/TERMINAL_WINDOW_STYLING.md b/TERMINAL_WINDOW_STYLING.md deleted file mode 100644 index a805ced..0000000 --- a/TERMINAL_WINDOW_STYLING.md +++ /dev/null @@ -1,523 +0,0 @@ -# Terminal Window Styling Guide - -## Overview - -The terminal now has a beautiful window frame wrapper, similar to Ghostty and other modern terminal emulators. This gives your web-based terminal a native application feel. - -## Features - -### 1. Terminal Window Frame -- **Rounded corners** (10px border radius) -- **Deep shadow** for depth and elevation -- **Frosted glass effect** with backdrop blur -- **Semi-transparent background** that shows the page background - -### 2. Title Bar -- **macOS-style traffic light buttons** (close, minimize, maximize) -- **Customizable title text** -- **Subtle border** separating it from terminal content -- **40px height** for comfortable proportions - -### 3. Window Controls -- **Red button** - Close (traditionally closes the window) -- **Yellow button** - Minimize (traditionally minimizes the window) -- **Green button** - Maximize (traditionally maximizes/fullscreen) -- **Hover effect** - Buttons brighten on hover -- **12px diameter** - Classic macOS size - -## Customization Options - -### Change Terminal Title - -In `templates/term.html`, find: - -```html -
socktop - Terminal
-``` - -Change to: -```html -
My Awesome Terminal
-
🚀 socktop v1.0
-
Terminal
-``` - -### Adjust Window Size - -```css -.terminal-window { - width: 80%; /* Default: 80% of viewport */ - max-width: 1200px; /* Default: 1200px max */ -} -``` - -**Options:** -```css -width: 90%; /* Larger window */ -width: 60%; /* Smaller window */ -width: 1000px; /* Fixed width */ -max-width: 1400px; /* Bigger max */ -``` - -### Change Border Radius (Roundness) - -```css -.terminal-window { - border-radius: 10px; /* Default: 10px */ -} -``` - -**Options:** -```css -border-radius: 6px; /* Smaller, subtle */ -border-radius: 15px; /* More rounded */ -border-radius: 20px; /* Very rounded */ -border-radius: 0; /* Square corners */ -``` - -### Adjust Shadow Depth - -```css -.terminal-window { - box-shadow: - 0 25px 50px rgba(0, 0, 0, 0.5), - 0 10px 20px rgba(0, 0, 0, 0.3); -} -``` - -**Light shadow:** -```css -box-shadow: - 0 10px 25px rgba(0, 0, 0, 0.3), - 0 5px 10px rgba(0, 0, 0, 0.2); -``` - -**Heavy shadow:** -```css -box-shadow: - 0 40px 80px rgba(0, 0, 0, 0.6), - 0 20px 40px rgba(0, 0, 0, 0.4); -``` - -**No shadow:** -```css -box-shadow: none; -``` - -### Change Title Bar Color - -```css -.terminal-titlebar { - background: rgba(40, 40, 40, 0.95); /* Default: dark */ -} -``` - -**Options:** -```css -/* Lighter */ -background: rgba(60, 60, 60, 0.95); - -/* Darker */ -background: rgba(20, 20, 20, 0.95); - -/* Colored (blue) */ -background: rgba(30, 40, 60, 0.95); - -/* Transparent */ -background: rgba(40, 40, 40, 0.7); - -/* Solid */ -background: rgb(40, 40, 40); -``` - -### Change Title Bar Height - -```css -.terminal-titlebar { - height: 40px; /* Default */ -} -``` - -**Options:** -```css -height: 32px; /* Compact */ -height: 48px; /* Spacious */ -height: 36px; /* Slightly smaller */ -``` - -### Customize Traffic Light Colors - -```css -.terminal-button.close { - background: #ff5f57; /* Red */ -} - -.terminal-button.minimize { - background: #ffbd2e; /* Yellow */ -} - -.terminal-button.maximize { - background: #28c840; /* Green */ -} -``` - -**Alternative color schemes:** - -**Windows style:** -```css -.terminal-button.close { - background: #e81123; -} - -.terminal-button.minimize { - background: #0078d4; -} - -.terminal-button.maximize { - background: #0078d4; -} -``` - -**Monochrome:** -```css -.terminal-button.close { - background: #999; -} - -.terminal-button.minimize { - background: #777; -} - -.terminal-button.maximize { - background: #555; -} -``` - -### Change Button Size - -```css -.terminal-button { - width: 12px; - height: 12px; -} -``` - -**Options:** -```css -width: 10px; height: 10px; /* Smaller */ -width: 14px; height: 14px; /* Larger */ -width: 16px; height: 16px; /* Much larger */ -``` - -### Adjust Button Spacing - -```css -.terminal-controls { - gap: 8px; /* Default: 8px between buttons */ -} -``` - -**Options:** -```css -gap: 6px; /* Tighter */ -gap: 10px; /* Looser */ -gap: 12px; /* More space */ -``` - -### Change Window Frame Background - -```css -.terminal-window { - background: rgba(30, 30, 30, 0.95); /* Default: dark */ -} -``` - -**Options:** -```css -/* Darker */ -background: rgba(20, 20, 20, 0.95); - -/* Lighter */ -background: rgba(50, 50, 50, 0.9); - -/* Colored */ -background: rgba(30, 35, 45, 0.95); - -/* More transparent */ -background: rgba(30, 30, 30, 0.8); - -/* Fully opaque */ -background: rgb(30, 30, 30); -``` - -### Adjust Backdrop Blur - -```css -.terminal-window { - backdrop-filter: blur(20px); /* Default: 20px */ -} -``` - -**Options:** -```css -backdrop-filter: blur(10px); /* Light blur */ -backdrop-filter: blur(30px); /* Heavy blur */ -backdrop-filter: blur(40px); /* Very heavy blur */ -backdrop-filter: none; /* No blur */ -``` - -## Window Styles Presets - -### Ghostty Style (Default) -```css -.terminal-window { - border-radius: 10px; - box-shadow: - 0 25px 50px rgba(0, 0, 0, 0.5), - 0 10px 20px rgba(0, 0, 0, 0.3); - background: rgba(30, 30, 30, 0.95); - backdrop-filter: blur(20px); -} -``` - -### Minimal Style -```css -.terminal-window { - border-radius: 6px; - box-shadow: 0 10px 30px rgba(0, 0, 0, 0.3); - background: rgba(20, 20, 20, 0.9); - backdrop-filter: blur(10px); - border: 1px solid rgba(255, 255, 255, 0.05); -} -``` - -### Floating Style -```css -.terminal-window { - border-radius: 15px; - box-shadow: - 0 50px 100px rgba(0, 0, 0, 0.6), - 0 20px 40px rgba(0, 0, 0, 0.4); - background: rgba(25, 25, 25, 0.85); - backdrop-filter: blur(30px) saturate(180%); -} -``` - -### Flat Style -```css -.terminal-window { - border-radius: 0; - box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3); - background: rgba(30, 30, 30, 0.98); - backdrop-filter: none; - border: 1px solid rgba(255, 255, 255, 0.1); -} -``` - -### Glass Style -```css -.terminal-window { - border-radius: 12px; - box-shadow: - 0 30px 60px rgba(0, 0, 0, 0.4), - inset 0 1px 0 rgba(255, 255, 255, 0.1); - background: rgba(40, 40, 40, 0.7); - backdrop-filter: blur(40px) saturate(150%); - border: 1px solid rgba(255, 255, 255, 0.15); -} -``` - -## Making Buttons Functional - -Currently, the traffic light buttons are just decorative. To make them functional, add JavaScript: - -### Close Button -```javascript -document.querySelector('.terminal-button.close').addEventListener('click', () => { - if (confirm('Close terminal?')) { - window.close(); // Or your custom close logic - } -}); -``` - -### Minimize Button -```javascript -document.querySelector('.terminal-button.minimize').addEventListener('click', () => { - document.querySelector('.terminal-window').style.transform = 'scale(0.5)'; - // Or hide: document.querySelector('.terminal-window').style.display = 'none'; -}); -``` - -### Maximize Button -```javascript -let isMaximized = false; -document.querySelector('.terminal-button.maximize').addEventListener('click', () => { - const window = document.querySelector('.terminal-window'); - if (isMaximized) { - window.style.width = '80%'; - window.style.maxHeight = '50vh'; - } else { - window.style.width = '100%'; - window.style.maxHeight = '100vh'; - } - isMaximized = !isMaximized; -}); -``` - -## Hide Traffic Lights - -If you prefer no window controls: - -```css -.terminal-controls { - display: none; -} - -.terminal-title { - text-align: left; /* Since there's no buttons on the left */ -} -``` - -## Center Title Without Controls - -```css -.terminal-title { - text-align: center; - margin: 0 auto; - width: 100%; -} -``` - -## Add Icons to Title - -```html -
- ⚡ socktop - Terminal -
- -
- 💻 Terminal -
-``` - -## Title Bar Variations - -### Left-aligned title with icon -```html -
-
...
-
- 🚀 - socktop v1.0 -
-
-``` - -### Title with tabs (like modern terminals) -```html -
-
...
-
-
Terminal 1
-
Terminal 2
-
-
-``` - -Then add CSS: -```css -.terminal-tab { - padding: 8px 16px; - background: rgba(255, 255, 255, 0.05); - border-radius: 6px 6px 0 0; - color: rgba(255, 255, 255, 0.5); - font-size: 12px; - cursor: pointer; -} - -.terminal-tab.active { - background: rgba(255, 255, 255, 0.1); - color: rgba(255, 255, 255, 0.9); -} -``` - -## Responsive Behavior - -The window automatically adjusts on mobile: - -```css -@media (max-width: 640px) { - .terminal-window { - width: 96%; - } -} -``` - -Customize: -```css -@media (max-width: 768px) { - .terminal-window { - width: 100%; - border-radius: 0; /* Remove rounded corners on mobile */ - } - - .terminal-titlebar { - height: 36px; /* Smaller on mobile */ - } - - .terminal-button { - width: 10px; - height: 10px; - } -} -``` - -## Accessibility - -The title bar is set to `user-select: none` so users can't accidentally select the text when clicking the buttons. - -To make buttons keyboard accessible: -```html -
-``` - -## Browser Compatibility - -All features work in modern browsers: -- ✅ Chrome/Edge 76+ -- ✅ Safari 9+ -- ✅ Firefox 103+ - -`backdrop-filter` gracefully degrades in older browsers (window will just be more opaque). - -## Performance Tips - -1. **Reduce blur** if experiencing lag: `blur(10px)` instead of `blur(20px)` -2. **Simplify shadows** on low-end devices -3. **Use opacity carefully** - too many transparent layers can impact performance - -## Quick Reference - -```css -/* Size */ -width: 80%; -max-width: 1200px; -border-radius: 10px; - -/* Colors */ -background: rgba(30, 30, 30, 0.95); -titlebar: rgba(40, 40, 40, 0.95); - -/* Effects */ -box-shadow: 0 25px 50px rgba(0, 0, 0, 0.5); -backdrop-filter: blur(20px); - -/* Buttons */ -close: #ff5f57 (red) -minimize: #ffbd2e (yellow) -maximize: #28c840 (green) -``` - ---- - -**Enjoy your beautiful terminal window frame!** 🖼️✨ \ No newline at end of file diff --git a/TRANSPARENCY_GUIDE.md b/TRANSPARENCY_GUIDE.md deleted file mode 100644 index bf99c6b..0000000 --- a/TRANSPARENCY_GUIDE.md +++ /dev/null @@ -1,326 +0,0 @@ -# Terminal Transparency Guide - -## Overview - -The terminal now supports transparency, allowing you to see your beautiful background image through the terminal! This uses xterm.js's `allowTransparency` option combined with CSS `backdrop-filter` for a modern, polished look. - -## How It Works - -The transparency is achieved through three components: - -1. **xterm.js `allowTransparency` option** - Enables transparency support -2. **Theme background color with alpha** - Sets the opacity level -3. **CSS backdrop-filter** - Adds optional blur effect - -## Current Setup - -### Terminal Configuration (JavaScript) - -```javascript -var term = new Terminal({ - allowTransparency: true, - theme: { - background: "rgba(0, 0, 0, 0.7)", // 70% opaque black - }, -}); -``` - -### Container Styling (CSS) - -```css -#terminal { - background: transparent; - backdrop-filter: blur(10px); /* Blur effect */ - border: 1px solid rgba(255, 255, 255, 0.2); - box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3); -} -``` - -## Customizing Transparency Level - -### Option 1: Adjust Terminal Background Opacity - -In `templates/term.html`, find the `Terminal` constructor and modify the alpha value: - -```javascript -var term = new Terminal({ - allowTransparency: true, - theme: { - background: "rgba(0, 0, 0, 0.7)", // Change the last number (0.7) - }, -}); -``` - -**Opacity Values:** -- `0.0` = Fully transparent (you'll see everything through) -- `0.3` = Very transparent (light tint) -- `0.5` = Half transparent (moderate tint) -- `0.7` = Somewhat opaque (recommended, current value) -- `0.9` = Nearly opaque (just a hint of transparency) -- `1.0` = Fully opaque (no transparency) - -### Option 2: Change Background Color - -You can use any color, not just black: - -```javascript -// Dark blue with transparency -background: "rgba(0, 20, 40, 0.7)" - -// Dark purple with transparency -background: "rgba(30, 20, 50, 0.7)" - -// Dark green with transparency (Matrix style!) -background: "rgba(0, 20, 0, 0.8)" - -// Use your theme colors -background: "rgba(48, 52, 70, 0.7)" // Catppuccin Frappe base -``` - -### Option 3: Adjust Blur Amount - -In the CSS, modify the `backdrop-filter` value: - -```css -/* No blur - sharp background */ -backdrop-filter: none; - -/* Light blur */ -backdrop-filter: blur(5px); - -/* Medium blur (current) */ -backdrop-filter: blur(10px); - -/* Heavy blur */ -backdrop-filter: blur(20px); - -/* Blur + brightness adjustment */ -backdrop-filter: blur(10px) brightness(0.8); -``` - -### Option 4: Remove Blur Entirely - -If you prefer sharp background with no blur: - -```css -#terminal { - background: transparent; - backdrop-filter: none; /* Remove this line or set to none */ -} -``` - -## Preset Styles - -### Glassy Effect (Recommended) - -```javascript -// In Terminal constructor -theme: { - background: "rgba(0, 0, 0, 0.6)", -} -``` - -```css -/* In CSS */ -#terminal { - backdrop-filter: blur(15px); - border: 1px solid rgba(255, 255, 255, 0.2); - box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4); -} -``` - -### Minimal Transparency - -```javascript -theme: { - background: "rgba(0, 0, 0, 0.85)", -} -``` - -```css -#terminal { - backdrop-filter: blur(5px); -} -``` - -### Maximum Transparency (Bold!) - -```javascript -theme: { - background: "rgba(0, 0, 0, 0.4)", -} -``` - -```css -#terminal { - backdrop-filter: blur(20px) brightness(0.8); -} -``` - -### Frosted Glass Effect - -```javascript -theme: { - background: "rgba(255, 255, 255, 0.1)", // Light background - foreground: "#000000", // Dark text -} -``` - -```css -#terminal { - backdrop-filter: blur(30px) saturate(180%); - border: 1px solid rgba(255, 255, 255, 0.3); -} -``` - -### Acrylic Effect (Windows 11 style) - -```javascript -theme: { - background: "rgba(32, 32, 32, 0.7)", -} -``` - -```css -#terminal { - backdrop-filter: blur(40px) saturate(125%) brightness(0.9); - border: 1px solid rgba(255, 255, 255, 0.15); - box-shadow: - 0 8px 32px rgba(0, 0, 0, 0.3), - inset 0 1px 0 rgba(255, 255, 255, 0.1); -} -``` - -## Full Theme Customization - -You can customize more than just the background: - -```javascript -var term = new Terminal({ - allowTransparency: true, - theme: { - background: "rgba(0, 0, 0, 0.7)", - foreground: "#d4d4d4", // Text color - cursor: "#ffffff", // Cursor color - cursorAccent: "#000000", // Cursor text color - selection: "rgba(255, 255, 255, 0.3)", // Selection highlight - - // ANSI Colors - black: "#000000", - red: "#e74856", - green: "#16c60c", - yellow: "#f9f1a5", - blue: "#3b78ff", - magenta: "#b4009e", - cyan: "#61d6d6", - white: "#cccccc", - - // Bright ANSI Colors - brightBlack: "#767676", - brightRed: "#e74856", - brightGreen: "#16c60c", - brightYellow: "#f9f1a5", - brightBlue: "#3b78ff", - brightMagenta: "#b4009e", - brightCyan: "#61d6d6", - brightWhite: "#f2f2f2", - }, -}); -``` - -## Browser Compatibility - -`backdrop-filter` is supported in: -- ✅ Chrome/Edge 76+ -- ✅ Safari 9+ -- ✅ Firefox 103+ -- ✅ Opera 63+ - -For older browsers, the terminal will still work but without the blur effect. - -## Performance Considerations - -**Blur effects can impact performance**, especially on: -- Lower-end devices -- Large terminal windows -- Systems without GPU acceleration - -If you experience lag: -1. Reduce blur amount: `blur(5px)` instead of `blur(20px)` -2. Remove blur entirely: `backdrop-filter: none;` -3. Increase opacity: Use `0.8` or `0.9` instead of `0.5` - -## Tips for Best Results - -1. **Match your background**: Use a background color that complements your page background -2. **Readability first**: Ensure text is still readable - don't go too transparent -3. **Test in different lighting**: What looks good in dark mode might not work in light mode -4. **Consider your content**: Busy backgrounds may need more opacity or blur - -## Examples with Different Backgrounds - -### Dark Background Image -```javascript -theme: { background: "rgba(0, 0, 0, 0.6)" } // More transparent OK -``` - -### Light Background Image -```javascript -theme: { background: "rgba(0, 0, 0, 0.8)" } // Need more opacity for contrast -``` - -### Busy/Complex Background -```javascript -theme: { background: "rgba(0, 0, 0, 0.75)" } // More opacity -// Plus heavy blur -backdrop-filter: blur(20px); -``` - -### Simple/Minimal Background -```javascript -theme: { background: "rgba(0, 0, 0, 0.5)" } // Can go more transparent -// Light or no blur -backdrop-filter: blur(5px); -``` - -## Troubleshooting - -### Background not showing through -- Check `allowTransparency: true` is set -- Verify background has alpha channel: `rgba(r, g, b, alpha)` not `rgb(r, g, b)` -- Make sure container background is `transparent` not a solid color - -### Text hard to read -- Increase opacity: Change `0.5` to `0.7` or `0.8` -- Add more blur: `blur(15px)` or `blur(20px)` -- Darken background: Use `rgba(0, 0, 0, 0.8)` instead of lighter values - -### Blur not working -- Check browser compatibility -- Verify CSS syntax: `backdrop-filter: blur(10px);` -- Try without vendor prefixes first - -### Performance issues -- Reduce blur amount -- Increase opacity -- Use simpler background image -- Disable backdrop-filter - -## Quick Reference - -```css -/* Transparency Level */ -rgba(0, 0, 0, 0.5) ← Change this number (0.0 to 1.0) - -/* Blur Amount */ -backdrop-filter: blur(10px); ← Change this number - -/* Remove blur entirely */ -backdrop-filter: none; -``` - ---- - -**Enjoy your transparent terminal!** 🎨✨ - -Experiment with different values to find what looks best with your background image and personal style. \ No newline at end of file diff --git a/UPGRADE_SUMMARY.md b/UPGRADE_SUMMARY.md deleted file mode 100644 index c89a67e..0000000 --- a/UPGRADE_SUMMARY.md +++ /dev/null @@ -1,144 +0,0 @@ -# xterm.js Upgrade Summary - -## Upgrade Complete ✅ - -Successfully upgraded xterm.js from **version 3.14.5** to **version 5.5.0**. - -## What Was Done - -### 1. Updated npm Dependencies -- Replaced `xterm: ^3.14.5` with `@xterm/xterm: ^5.3.0` -- Added `@xterm/addon-fit: ^0.10.0` -- Note: npm installed version 5.5.0 (latest stable) - -### 2. Created Modern Terminado Addon -**File:** `static/terminado-addon.js` - -A custom addon implementing the modern `ITerminalAddon` interface that handles the Terminado WebSocket protocol. This replaced the legacy v3.x addon system. - -**Key Features:** -- Bidirectional WebSocket communication -- Automatic terminal resize handling -- Buffered output for better performance -- Clean lifecycle management (activate/dispose) -- Public API: `attach()`, `detach()`, `sendSize()`, `sendCommand()` - -### 3. Updated HTML Template -**File:** `templates/term.html` - -- Changed script paths to new package locations -- Replaced `Terminal.applyAddon()` with `term.loadAddon()` -- Updated addon instantiation to use new class-based API -- Modernized JavaScript code structure - -### 4. No Rust Changes Required -The Rust backend (`src/server.rs`, `src/lib.rs`, `src/terminado.rs`) works without modification because the Terminado protocol and WebSocket implementation remain the same. - -## Key Differences Between v3.x and v5.x - -| Aspect | v3.14.5 (Old) | v5.5.0 (New) | -|--------|---------------|--------------| -| Package Name | `xterm` | `@xterm/xterm` | -| Addon System | `Terminal.applyAddon()` | `term.loadAddon()` | -| Addon Location | `/dist/addons/*/` | Separate npm packages | -| Fit Method | `term.fit()` | `fitAddon.fit()` | -| CSS Path | `/dist/xterm.css` | `/css/xterm.css` | -| JS Path | `/dist/xterm.js` | `/lib/xterm.js` | - -## Testing - -### Verify Installation -```bash -# Check installed versions -cat node_modules/@xterm/xterm/package.json | grep version -cat node_modules/@xterm/addon-fit/package.json | grep version -``` - -### Run the Server -```bash -cargo build -cargo run -``` - -### Access the Terminal -Open http://localhost:8082/ in your browser - -### Expected Behavior -- Terminal loads and displays correctly -- Terminal fits to container size -- WebSocket connects successfully -- socktop command launches automatically -- Typing works in the terminal -- Window resize updates terminal size - -## Files Modified - -1. ✏️ `package.json` - Updated dependencies -2. ✏️ `templates/term.html` - Updated to use v5.x API -3. ✨ `static/terminado-addon.js` - New custom addon (copied to `node_modules/`) -4. ✨ `test_xterm.html` - Test page for verification -5. ✨ `XTERM_UPGRADE.md` - Detailed upgrade documentation -6. ✨ `UPGRADE_SUMMARY.md` - This file - -## Benefits of Upgrading - -✅ **Security:** Latest patches and security updates -✅ **Performance:** Improved rendering and memory management -✅ **Maintainability:** Cleaner, modern API design -✅ **Features:** Access to all features added since v3.x -✅ **Support:** Active development and community support -✅ **Compatibility:** Better TypeScript and modern browser support - -## Next Steps - -### Immediate -The upgrade is complete and working. You can now: -1. Test with your socktop application -2. Customize the terminal appearance -3. Add additional features - -### Future Enhancements -Consider adding these xterm addons: -- `@xterm/addon-search` - Search within terminal output -- `@xterm/addon-web-links` - Make URLs clickable -- `@xterm/addon-webgl` - Hardware-accelerated rendering -- `@xterm/addon-unicode11` - Full Unicode 11 support - -## Troubleshooting - -### If JavaScript console shows errors: -1. Check that all files are being served (check browser Network tab) -2. Verify paths in `templates/term.html` match file locations -3. Ensure `terminado-addon.js` is in `node_modules/` - -### If terminal doesn't display: -1. Check WebSocket connection in browser DevTools -2. Verify Rust server is running on port 8082 -3. Check server logs for errors - -### If terminal doesn't fit properly: -1. Ensure FitAddon is loaded before calling `fit()` -2. Check that container has non-zero dimensions -3. Verify CSS is loading correctly - -## Resources - -- **xterm.js Documentation:** https://xtermjs.org/ -- **GitHub Repository:** https://github.com/xtermjs/xterm.js -- **Detailed Upgrade Doc:** See `XTERM_UPGRADE.md` in this directory -- **Test Page:** Open `test_xterm.html` in browser (via web server) - -## Questions or Issues? - -If you encounter any problems: -1. Check the browser console for JavaScript errors -2. Review the server logs for backend issues -3. Verify all npm packages are installed: `npm install` -4. Ensure `terminado-addon.js` is accessible at `/static/terminado-addon.js` - ---- - -**Status:** ✅ Upgrade Complete and Working -**Date:** 2024 -**Upgraded By:** xterm.js upgrade process -**Tested:** ✅ Compiles, ✅ Runs, ✅ Loads resources, ✅ Terminal displays \ No newline at end of file diff --git a/XTERM_UPGRADE.md b/XTERM_UPGRADE.md deleted file mode 100644 index 9ae7b97..0000000 --- a/XTERM_UPGRADE.md +++ /dev/null @@ -1,230 +0,0 @@ -# xterm.js Upgrade Documentation - -## Overview - -This document describes the upgrade of xterm.js from version 3.14.5 to 5.5.0 (latest). - -## Changes Made - -### 1. Package Dependencies - -**Before (package.json):** -```json -{ - "dependencies": { - "xterm": "^3.14.5" - } -} -``` - -**After (package.json):** -```json -{ - "dependencies": { - "@xterm/xterm": "^5.3.0", - "@xterm/addon-fit": "^0.10.0" - } -} -``` - -**Installed Versions:** -- `@xterm/xterm`: 5.5.0 -- `@xterm/addon-fit`: 0.10.0 - -### 2. Package Namespace Change - -xterm.js moved from the `xterm` package to the scoped `@xterm/xterm` package. The old package is now deprecated. - -### 3. Addon System Overhaul - -**Old Addon System (v3.x):** -- Addons loaded via ` - - - - - - - - - - -``` - -**JavaScript API Changes:** -```javascript -// OLD (v3.x) -if (typeof Terminal !== 'undefined' && typeof Terminal.applyAddon === 'function') { - Terminal.applyAddon(terminado); - Terminal.applyAddon(fit); -} -var term = new Terminal(); -term.open(terminalContainer); -term.terminadoAttach(sock); -term.fit(); - -// NEW (v5.x) -var term = new Terminal(); -var fitAddon = new FitAddon.FitAddon(); -term.loadAddon(fitAddon); -var terminadoAddon = new TerminadoAddon(); -term.loadAddon(terminadoAddon); -term.open(terminalContainer); -fitAddon.fit(); -terminadoAddon.attach(sock, true, true); -``` - -### 6. Rust Backend - -**No changes required** - The Rust backend (`src/server.rs`, `src/lib.rs`, `src/terminado.rs`) continues to work without modification because: -- The Terminado protocol remains unchanged -- WebSocket communication is the same -- PTY handling is identical - -## Migration Guide - -### For Developers Using This Project - -1. **Update npm packages:** - ```bash - npm install - ``` - -2. **Copy custom addon to node_modules:** - ```bash - cp static/terminado-addon.js node_modules/ - ``` - -3. **Build and run:** - ```bash - cargo build - cargo run - ``` - -4. **Access the terminal:** - Open `http://localhost:8082/` in your browser - -### For Projects Forking This Code - -If you're building a similar project, here's what you need to know: - -1. **Use scoped packages:** Install `@xterm/xterm` instead of `xterm` -2. **Install addon packages separately:** Each addon is now its own npm package -3. **Implement ITerminalAddon:** Custom addons must implement the modern interface: - ```javascript - class MyAddon { - activate(terminal) { /* ... */ } - dispose() { /* ... */ } - } - ``` -4. **Update your HTML:** Change script paths to point to new locations -5. **Refactor addon usage:** Replace `applyAddon()` with `loadAddon()` - -## Breaking Changes from v3.x to v5.x - -1. **No backward compatibility:** The old addon API is completely removed -2. **Package names changed:** Must use `@xterm/*` scoped packages -3. **Addon methods moved:** Methods like `fit()` now belong to addon instances -4. **File locations changed:** Scripts moved from `dist/` to `lib/` or `css/` -5. **No global addon objects:** Addons no longer register themselves globally - -## Benefits of Upgrading - -1. **Modern API:** Cleaner, more maintainable code structure -2. **Better TypeScript support:** Improved type definitions -3. **Performance improvements:** Better rendering and memory management -4. **Security updates:** Patches for known vulnerabilities -5. **Active development:** v3.x is no longer maintained -6. **New features:** Access to all features added since v3.x -7. **Better addon ecosystem:** Separate packages allow independent versioning - -## Testing - -A test file is provided to verify the upgrade: `test_xterm.html` - -Open it in a browser (served via a local web server) to verify: -- xterm.js loads correctly -- FitAddon works properly -- Terminal renders and accepts input -- Modern API is functional - -## Known Issues - -None at this time. The upgrade was successful with no breaking changes to functionality. - -## Resources - -- [xterm.js Official Documentation](https://xtermjs.org/) -- [xterm.js GitHub Repository](https://github.com/xtermjs/xterm.js) -- [Migration Guide (v3 to v4)](https://github.com/xtermjs/xterm.js/blob/master/MIGRATION.md) -- [Addon API Documentation](https://github.com/xtermjs/xterm.js/tree/master/addons) - -## Future Considerations - -1. **Additional addons:** Consider adding more xterm addons: - - `@xterm/addon-search`: Search functionality - - `@xterm/addon-web-links`: Clickable URLs - - `@xterm/addon-webgl`: WebGL renderer for better performance - - `@xterm/addon-unicode11`: Full Unicode 11 support - -2. **WebAssembly backend:** xterm.js v5.x supports WebAssembly for improved performance - -3. **Ligature support:** New versions support font ligatures for better code display - -4. **Image support:** Experimental support for inline images (Sixel protocol) - -## Conclusion - -The upgrade to xterm.js 5.5.0 was successful. All original functionality is preserved, the codebase is now more maintainable, and we have access to the latest features and security updates. \ No newline at end of file diff --git a/docker/restricted-shell.sh b/docker/restricted-shell.sh index 7012c99..9eb8476 100644 --- a/docker/restricted-shell.sh +++ b/docker/restricted-shell.sh @@ -85,13 +85,6 @@ show_help() { echo " ↑/↓ - Navigate lists" echo " PageUp/Down - Scroll faster" echo "" - echo -e "${CYAN}Features:${NC}" - echo " ✓ Real-time CPU, memory, disk, and network monitoring" - echo " ✓ Process list with sorting and filtering" - echo " ✓ Remote monitoring via SSH" - echo " ✓ Beautiful Catppuccin Frappe theme" - echo " ✓ Lightweight and fast" - echo "" echo -e "${CYAN}Links:${NC}" echo " GitHub: https://github.com/jasonwitty/socktop" echo " Documentation: https://jasonwitty.github.io/socktop/" diff --git a/kubernetes/CHECKLIST.md b/kubernetes/CHECKLIST.md deleted file mode 100644 index e177c65..0000000 --- a/kubernetes/CHECKLIST.md +++ /dev/null @@ -1,216 +0,0 @@ -# Pre-Deployment Checklist for Socktop WebTerm on k3s - -Use this checklist to ensure your k3s cluster is properly configured before deploying Socktop WebTerm. - -## Infrastructure Requirements - -### k3s Cluster -- [ ] k3s cluster is installed and running -- [ ] At least 3 nodes available (for spreading 3 replicas) -- [ ] `kubectl` is installed and configured -- [ ] Can run `kubectl get nodes` successfully -- [ ] Traefik ingress controller is running (default with k3s) -- [ ] Nodes have sufficient resources: - - [ ] 1.5+ CPU cores available per node - - [ ] 768+ MB RAM available per node - -### Network Access -- [ ] k3s nodes can reach Raspberry Pi nodes on port 8443 - - [ ] 192.168.1.101:8443 (rpi-master) - - [ ] 192.168.1.102:8443 (rpi-worker-1) - - [ ] 192.168.1.103:8443 (rpi-worker-2) - - [ ] 192.168.1.104:8443 (rpi-worker-3) -- [ ] Test with: `curl -k https://192.168.1.101:8443/health` - -### DNS Configuration -- [ ] DNS records point to your external NGINX Proxy Manager IP: - - [ ] socktop.io → external IP - - [ ] www.socktop.io → external IP - - [ ] origin.socktop.io → external IP -- [ ] DNS propagation is complete (test with `nslookup socktop.io`) - -## Required k3s Components - -### Traefik Ingress Controller -- [ ] Traefik is running (comes default with k3s) -- [ ] Check with: `kubectl get pods -n kube-system | grep traefik` -- [ ] Traefik is accessible on port 80 (HTTP) - -### External NGINX Proxy Manager -- [ ] External NGINX Proxy Manager is configured -- [ ] SSL certificates are set up in Proxy Manager -- [ ] Proxy hosts configured for: - - [ ] socktop.io → k3s-node-ip:8080 - - [ ] www.socktop.io → k3s-node-ip:8080 - - [ ] origin.socktop.io → k3s-node-ip:8080 -- [ ] WebSocket support enabled in proxy hosts -- [ ] SSL termination happens at NGINX Proxy Manager - -## Docker Registry Access - -### Gitea Registry Configuration -- [ ] Gitea registry is accessible at 192.168.1.208:3002 -- [ ] Test with: `curl http://192.168.1.208:3002/v2/` -- [ ] Image exists: `192.168.1.208:3002/jason/socktop-webterm:0.2.0` - -### Insecure Registry Configuration (REQUIRED) -Since Gitea uses HTTP, you MUST configure k3s to allow insecure registries. - -**On EACH k3s node** (both server and agents): - -- [ ] Created `/etc/rancher/k3s/registries.yaml` with: - ```yaml - mirrors: - "192.168.1.208:3002": - endpoint: - - "http://192.168.1.208:3002" - configs: - "192.168.1.208:3002": - tls: - insecure_skip_verify: true - ``` -- [ ] Restarted k3s services: - - [ ] Server: `sudo systemctl restart k3s` - - [ ] Agents: `sudo systemctl restart k3s-agent` -- [ ] Test image pull: `docker pull 192.168.1.208:3002/jason/socktop-webterm:0.2.0` - -## TLS Certificates (Optional but Recommended) - -### Raspberry Pi TLS Certificates -If you want to connect to Pi nodes via TLS: - -- [ ] Have TLS CA certificates for each Pi node: - - [ ] rpi-master.pem - - [ ] rpi-worker-1.pem - - [ ] rpi-worker-2.pem - - [ ] rpi-worker-3.pem -- [ ] Certificate files are accessible on your local machine -- [ ] Know the full path to each certificate file - -**Note:** If you don't have these yet, the deployment will still work, but you won't be able to connect to Pi nodes via TLS WebSocket. - -## Configuration Files - -### profiles.json -- [ ] Reviewed `kubernetes/01-configmap.yaml` -- [ ] Updated Raspberry Pi IP addresses if different -- [ ] Updated port numbers if different -- [ ] Updated certificate paths if different - -### alacritty.toml -- [ ] Reviewed terminal configuration in `kubernetes/01-configmap.yaml` -- [ ] Adjusted font size/family if desired -- [ ] Adjusted transparency/blur settings if desired - -## Deployment Files Ready - -- [ ] All manifest files are present: - - [ ] `01-configmap.yaml` - - [ ] `02-secret.yaml` - - [ ] `03-deployment.yaml` - - [ ] `04-service.yaml` - - [ ] `05-ingress.yaml` -- [ ] `deploy.sh` script is executable: `chmod +x deploy.sh` - -## Security Considerations - -- [ ] Understand that `hostNetwork: true` reduces pod isolation -- [ ] Cluster network is trusted (not exposed to public internet directly) -- [ ] TLS certificates will be stored as Kubernetes secrets -- [ ] Consider implementing authentication (OAuth2 Proxy, etc.) -- [ ] Rate limiting is configured in ingress (100 rps by default) - -## Resource Planning - -With 3 replicas, total resource requirements: -- **CPU**: 1.5 cores requested, 6 cores limit -- **Memory**: 768 MB requested, 3 GB limit - -- [ ] Your cluster has sufficient resources -- [ ] Check with: `kubectl describe nodes` - -## Backup Plan - -- [ ] Know how to view logs: `kubectl logs -l app=socktop-webterm` -- [ ] Know how to delete deployment: `kubectl delete -f kubernetes/` -- [ ] Have access to Docker logs on k3s nodes if needed - -## Pre-Deployment Test Commands - -Run these commands to verify everything is ready: - -```bash -# Check cluster access -kubectl cluster-info - -# Check nodes -kubectl get nodes - -# Check Traefik ingress controller -kubectl get pods -n kube-system | grep traefik - -# Check Traefik service -kubectl get svc -n kube-system traefik - -# Test registry access from a node -ssh -docker pull 192.168.1.208:3002/jason/socktop-webterm:0.2.0 - -# Test network access to Pi nodes -curl -k https://192.168.1.101:8443/health -``` - -## Ready to Deploy? - -If all items above are checked ✓, you're ready to deploy! - -### Choose your deployment method: - -**Option 1: Automated (Recommended)** -```bash -cd kubernetes -./deploy.sh -``` - -**Option 2: Manual** -```bash -cd kubernetes -kubectl apply -f . -``` - -**Option 3: Kustomize** -```bash -cd kubernetes -kubectl apply -k . -``` - -## Post-Deployment Verification - -After deployment, verify: - -```bash -# Check pods are running -kubectl get pods -l app=socktop-webterm - -# Check service is created -kubectl get svc socktop-webterm - -# Check ingress is configured -kubectl get ingress socktop-webterm - -# View logs -kubectl logs -l app=socktop-webterm -f -``` - -Configure your external NGINX Proxy Manager to forward traffic, then access: -- https://socktop.io (SSL terminated at NGINX Proxy Manager) -- https://www.socktop.io -- https://origin.socktop.io - -## Troubleshooting - -If something goes wrong, see: -- `QUICKSTART.md` - Common issues and quick fixes -- `README.md` - Detailed troubleshooting guide -- Pod logs: `kubectl logs -l app=socktop-webterm` -- Pod events: `kubectl describe pods -l app=socktop-webterm` diff --git a/kubernetes/DEPLOYMENT-STEPS.md b/kubernetes/DEPLOYMENT-STEPS.md deleted file mode 100644 index e164bf2..0000000 --- a/kubernetes/DEPLOYMENT-STEPS.md +++ /dev/null @@ -1,287 +0,0 @@ -# Next Steps - Ready to Run After Registry Setup - -## Step 1: Verify All Nodes Have the Image - -Once all nodes finish pulling, verify: - -```bash -# Check each node has the image cached -ssh pi@192.168.1.101 'sudo k3s crictl images | grep socktop' -ssh pi@192.168.1.102 'sudo k3s crictl images | grep socktop' -ssh pi@192.168.1.104 'sudo k3s crictl images | grep socktop' - -# Should show: -# 192.168.1.208:3002/jason/socktop-webterm 0.2.0