647 lines
15 KiB
Markdown
647 lines
15 KiB
Markdown
# Terminal Feature Integration Guide
|
|
|
|
## Overview
|
|
|
|
This document provides step-by-step instructions for integrating the terminal feature with the backend infrastructure. The terminal feature requires WebSocket support and SSH proxy capabilities that cannot run directly in Cloudflare Workers due to PTY limitations.
|
|
|
|
---
|
|
|
|
## Backend Architecture Decision
|
|
|
|
Since Cloudflare Workers cannot create PTY (pseudo-terminal) processes required for tmux, you have **two implementation options**:
|
|
|
|
### Option 1: Separate WebSocket Server (Recommended)
|
|
|
|
Run a Node.js WebSocket server on your DigitalOcean droplet that handles terminal connections.
|
|
|
|
**Pros:**
|
|
- Clean separation of concerns
|
|
- Full control over PTY/tmux integration
|
|
- No Cloudflare Worker modifications needed
|
|
- Better security (SSH keys never leave your droplet)
|
|
|
|
**Cons:**
|
|
- Additional server to maintain
|
|
- Need to expose WebSocket port
|
|
|
|
### Option 2: Hybrid Cloudflare + Droplet Service
|
|
|
|
Use Cloudflare Durable Objects to proxy WebSocket connections to a backend service on your droplet.
|
|
|
|
**Pros:**
|
|
- Leverages existing Cloudflare infrastructure
|
|
- Can reuse authentication
|
|
- Single entry point for clients
|
|
|
|
**Cons:**
|
|
- More complex setup
|
|
- Still requires separate service on droplet
|
|
- May have latency overhead
|
|
|
|
---
|
|
|
|
## Option 1: Separate WebSocket Server (Step-by-Step)
|
|
|
|
### Step 1: Create WebSocket Server on Droplet
|
|
|
|
Create a new file on your DigitalOcean droplet: `/opt/terminal-server/server.js`
|
|
|
|
```javascript
|
|
import WebSocket from 'ws'
|
|
import { TerminalProxyManager, SSHConfig } from './TerminalProxy.js'
|
|
|
|
const PORT = 8080
|
|
const wss = new WebSocket.Server({ port: PORT })
|
|
|
|
// Load SSH config from environment or config file
|
|
const sshConfig: SSHConfig = {
|
|
host: 'localhost', // Connect to same droplet
|
|
port: 22,
|
|
username: process.env.SSH_USER || 'canvas-terminal',
|
|
privateKey: fs.readFileSync(process.env.SSH_KEY_PATH || '/opt/terminal-server/key')
|
|
}
|
|
|
|
const proxyManager = new TerminalProxyManager()
|
|
|
|
console.log(`Terminal WebSocket server listening on port ${PORT}`)
|
|
|
|
wss.on('connection', (ws, req) => {
|
|
const url = new URL(req.url, `ws://localhost:${PORT}`)
|
|
const sessionId = url.pathname.split('/').pop()
|
|
|
|
// TODO: Add authentication
|
|
const userId = req.headers['x-user-id'] || 'anonymous'
|
|
|
|
console.log(`Client connected: ${userId}`)
|
|
|
|
const proxy = proxyManager.getProxy(userId, sshConfig)
|
|
let currentSession: string | null = null
|
|
|
|
ws.on('message', async (data) => {
|
|
try {
|
|
const message = JSON.parse(data.toString())
|
|
|
|
switch (message.type) {
|
|
case 'init':
|
|
// Attach to tmux session
|
|
const connectionId = `${userId}-conn`
|
|
|
|
if (!proxy.isConnected(connectionId)) {
|
|
await proxy.connect(connectionId)
|
|
}
|
|
|
|
currentSession = await proxy.attachSession(
|
|
connectionId,
|
|
message.sessionId,
|
|
message.cols || 80,
|
|
message.rows || 24,
|
|
(output) => {
|
|
ws.send(JSON.stringify({ type: 'output', data: output }))
|
|
},
|
|
() => {
|
|
ws.send(JSON.stringify({ type: 'status', status: 'disconnected' }))
|
|
}
|
|
)
|
|
|
|
ws.send(JSON.stringify({ type: 'status', status: 'connected' }))
|
|
break
|
|
|
|
case 'input':
|
|
if (currentSession) {
|
|
await proxy.sendInput(currentSession, message.data)
|
|
}
|
|
break
|
|
|
|
case 'resize':
|
|
if (currentSession) {
|
|
await proxy.resize(currentSession, message.cols, message.rows)
|
|
}
|
|
break
|
|
|
|
case 'list_sessions':
|
|
const connectionId2 = `${userId}-conn`
|
|
if (!proxy.isConnected(connectionId2)) {
|
|
await proxy.connect(connectionId2)
|
|
}
|
|
const sessions = await proxy.listSessions(connectionId2)
|
|
ws.send(JSON.stringify({ type: 'sessions', sessions }))
|
|
break
|
|
|
|
case 'create_session':
|
|
const connectionId3 = `${userId}-conn`
|
|
if (!proxy.isConnected(connectionId3)) {
|
|
await proxy.connect(connectionId3)
|
|
}
|
|
const newSession = await proxy.createSession(connectionId3, message.name)
|
|
ws.send(JSON.stringify({ type: 'session_created', sessionId: newSession }))
|
|
break
|
|
|
|
case 'detach':
|
|
if (currentSession) {
|
|
await proxy.detachSession(currentSession)
|
|
currentSession = null
|
|
ws.send(JSON.stringify({ type: 'status', status: 'detached' }))
|
|
}
|
|
break
|
|
}
|
|
} catch (err) {
|
|
console.error('Error handling message:', err)
|
|
ws.send(JSON.stringify({ type: 'error', message: err.message }))
|
|
}
|
|
})
|
|
|
|
ws.on('close', async () => {
|
|
console.log(`Client disconnected: ${userId}`)
|
|
if (currentSession) {
|
|
await proxy.detachSession(currentSession)
|
|
}
|
|
})
|
|
|
|
ws.on('error', (err) => {
|
|
console.error('WebSocket error:', err)
|
|
})
|
|
})
|
|
|
|
// Cleanup on shutdown
|
|
process.on('SIGINT', async () => {
|
|
console.log('Shutting down...')
|
|
await proxyManager.cleanup()
|
|
wss.close()
|
|
process.exit(0)
|
|
})
|
|
```
|
|
|
|
### Step 2: Copy TerminalProxy.ts to Droplet
|
|
|
|
Copy `/worker/TerminalProxy.ts` to your droplet and convert it to work with Node.js:
|
|
|
|
```bash
|
|
# On your local machine
|
|
scp worker/TerminalProxy.ts your-droplet:/opt/terminal-server/TerminalProxy.js
|
|
```
|
|
|
|
### Step 3: Install Dependencies on Droplet
|
|
|
|
```bash
|
|
ssh your-droplet
|
|
cd /opt/terminal-server
|
|
npm init -y
|
|
npm install ws ssh2
|
|
```
|
|
|
|
### Step 4: Create systemd Service
|
|
|
|
Create `/etc/systemd/system/terminal-server.service`:
|
|
|
|
```ini
|
|
[Unit]
|
|
Description=Terminal WebSocket Server
|
|
After=network.target
|
|
|
|
[Service]
|
|
Type=simple
|
|
User=canvas-terminal
|
|
WorkingDirectory=/opt/terminal-server
|
|
Environment="NODE_ENV=production"
|
|
Environment="SSH_USER=canvas-terminal"
|
|
Environment="SSH_KEY_PATH=/opt/terminal-server/key"
|
|
ExecStart=/usr/bin/node /opt/terminal-server/server.js
|
|
Restart=on-failure
|
|
RestartSec=10
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
```
|
|
|
|
Enable and start:
|
|
|
|
```bash
|
|
sudo systemctl enable terminal-server
|
|
sudo systemctl start terminal-server
|
|
sudo systemctl status terminal-server
|
|
```
|
|
|
|
### Step 5: Configure Firewall
|
|
|
|
```bash
|
|
# Allow WebSocket connections
|
|
sudo ufw allow 8080/tcp
|
|
|
|
# Or if using specific IPs
|
|
sudo ufw allow from YOUR_CLOUDFLARE_IP to any port 8080
|
|
```
|
|
|
|
### Step 6: Update Frontend WebSocket URL
|
|
|
|
Modify `/src/components/TerminalContent.tsx`:
|
|
|
|
```typescript
|
|
const connectWebSocket = () => {
|
|
// Update with your droplet IP
|
|
const wsUrl = `wss://YOUR_DROPLET_IP:8080/terminal/${sessionId}`
|
|
const ws = new WebSocket(wsUrl)
|
|
// ... rest of code
|
|
}
|
|
```
|
|
|
|
### Step 7: Optional - Use nginx as Reverse Proxy
|
|
|
|
Create `/etc/nginx/sites-available/terminal-ws`:
|
|
|
|
```nginx
|
|
upstream terminal_backend {
|
|
server 127.0.0.1:8080;
|
|
}
|
|
|
|
server {
|
|
listen 443 ssl http2;
|
|
server_name terminal.yourdomain.com;
|
|
|
|
ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
|
|
ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
|
|
|
|
location / {
|
|
proxy_pass http://terminal_backend;
|
|
proxy_http_version 1.1;
|
|
proxy_set_header Upgrade $http_upgrade;
|
|
proxy_set_header Connection "upgrade";
|
|
proxy_set_header Host $host;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_set_header X-Forwarded-Proto $scheme;
|
|
|
|
# WebSocket specific
|
|
proxy_read_timeout 86400;
|
|
proxy_send_timeout 86400;
|
|
}
|
|
}
|
|
```
|
|
|
|
Enable and reload:
|
|
|
|
```bash
|
|
sudo ln -s /etc/nginx/sites-available/terminal-ws /etc/nginx/sites-enabled/
|
|
sudo nginx -t
|
|
sudo systemctl reload nginx
|
|
```
|
|
|
|
---
|
|
|
|
## Option 2: Cloudflare Worker Integration
|
|
|
|
If you prefer to proxy through Cloudflare, add these routes to `worker/AutomergeDurableObject.ts`:
|
|
|
|
```typescript
|
|
import { TerminalProxyManager } from './TerminalProxy'
|
|
|
|
export class AutomergeDurableObject {
|
|
// Add to existing class
|
|
private terminalProxyManager: TerminalProxyManager | null = null
|
|
|
|
private getTerminalProxy() {
|
|
if (!this.terminalProxyManager) {
|
|
this.terminalProxyManager = new TerminalProxyManager()
|
|
}
|
|
return this.terminalProxyManager
|
|
}
|
|
|
|
// Add to router (after line 155)
|
|
private readonly router = AutoRouter({
|
|
// ... existing routes ...
|
|
})
|
|
// ... existing routes ...
|
|
|
|
// Terminal WebSocket endpoint
|
|
.get("/terminal/ws/:sessionId", async (request) => {
|
|
const upgradeHeader = request.headers.get("Upgrade")
|
|
if (upgradeHeader !== "websocket") {
|
|
return new Response("Expected Upgrade: websocket", { status: 426 })
|
|
}
|
|
|
|
const [client, server] = Object.values(new WebSocketPair())
|
|
|
|
// Handle WebSocket connection
|
|
server.accept()
|
|
|
|
const proxyManager = this.getTerminalProxy()
|
|
const userId = "user-123" // TODO: Get from auth
|
|
|
|
// Get SSH config from environment or secrets
|
|
const sshConfig = {
|
|
host: request.env.TERMINAL_SSH_HOST,
|
|
port: 22,
|
|
username: request.env.TERMINAL_SSH_USER,
|
|
privateKey: request.env.TERMINAL_SSH_KEY
|
|
}
|
|
|
|
const proxy = proxyManager.getProxy(userId, sshConfig)
|
|
let currentSession: string | null = null
|
|
|
|
server.addEventListener("message", async (event) => {
|
|
try {
|
|
const message = JSON.parse(event.data as string)
|
|
|
|
// Handle message types similar to Option 1
|
|
// ... (implementation same as server.js above)
|
|
} catch (err) {
|
|
server.send(JSON.stringify({ type: "error", message: err.message }))
|
|
}
|
|
})
|
|
|
|
return new Response(null, {
|
|
status: 101,
|
|
webSocket: client
|
|
})
|
|
})
|
|
|
|
// List tmux sessions
|
|
.get("/terminal/sessions", async (request) => {
|
|
const userId = "user-123" // TODO: Get from auth
|
|
const proxyManager = this.getTerminalProxy()
|
|
|
|
const sshConfig = {
|
|
host: request.env.TERMINAL_SSH_HOST,
|
|
port: 22,
|
|
username: request.env.TERMINAL_SSH_USER,
|
|
privateKey: request.env.TERMINAL_SSH_KEY
|
|
}
|
|
|
|
const proxy = proxyManager.getProxy(userId, sshConfig)
|
|
const connectionId = `${userId}-conn`
|
|
|
|
if (!proxy.isConnected(connectionId)) {
|
|
await proxy.connect(connectionId)
|
|
}
|
|
|
|
const sessions = await proxy.listSessions(connectionId)
|
|
|
|
return new Response(JSON.stringify({ sessions }), {
|
|
headers: {
|
|
"Content-Type": "application/json",
|
|
"Access-Control-Allow-Origin": "*"
|
|
}
|
|
})
|
|
})
|
|
|
|
// Create new tmux session
|
|
.post("/terminal/sessions", async (request) => {
|
|
const userId = "user-123" // TODO: Get from auth
|
|
const { name } = await request.json() as { name: string }
|
|
|
|
const proxyManager = this.getTerminalProxy()
|
|
const sshConfig = {
|
|
host: request.env.TERMINAL_SSH_HOST,
|
|
port: 22,
|
|
username: request.env.TERMINAL_SSH_USER,
|
|
privateKey: request.env.TERMINAL_SSH_KEY
|
|
}
|
|
|
|
const proxy = proxyManager.getProxy(userId, sshConfig)
|
|
const connectionId = `${userId}-conn`
|
|
|
|
if (!proxy.isConnected(connectionId)) {
|
|
await proxy.connect(connectionId)
|
|
}
|
|
|
|
const sessionId = await proxy.createSession(connectionId, name)
|
|
|
|
return new Response(JSON.stringify({ sessionId }), {
|
|
headers: {
|
|
"Content-Type": "application/json",
|
|
"Access-Control-Allow-Origin": "*"
|
|
}
|
|
})
|
|
})
|
|
}
|
|
```
|
|
|
|
**Note:** Cloudflare Workers have limitations:
|
|
- 128MB memory limit
|
|
- 30-second CPU time limit (50ms for free tier)
|
|
- ssh2 may not work due to crypto limitations
|
|
|
|
**Recommendation:** Use Option 1 (separate WebSocket server) for better reliability.
|
|
|
|
---
|
|
|
|
## Environment Variables
|
|
|
|
Add to `.env` or Cloudflare Worker secrets:
|
|
|
|
```bash
|
|
TERMINAL_SSH_HOST=165.227.XXX.XXX
|
|
TERMINAL_SSH_PORT=22
|
|
TERMINAL_SSH_USER=canvas-terminal
|
|
TERMINAL_SSH_KEY="-----BEGIN OPENSSH PRIVATE KEY-----
|
|
...
|
|
-----END OPENSSH PRIVATE KEY-----"
|
|
```
|
|
|
|
Set Cloudflare secrets:
|
|
|
|
```bash
|
|
wrangler secret put TERMINAL_SSH_HOST
|
|
wrangler secret put TERMINAL_SSH_USER
|
|
wrangler secret put TERMINAL_SSH_KEY
|
|
```
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
### 1. Test WebSocket Server
|
|
|
|
```bash
|
|
# Install wscat
|
|
npm install -g wscat
|
|
|
|
# Connect to server
|
|
wscat -c ws://YOUR_DROPLET_IP:8080/terminal/test-session
|
|
|
|
# Send test message
|
|
> {"type":"list_sessions"}
|
|
```
|
|
|
|
### 2. Test from Browser Console
|
|
|
|
```javascript
|
|
const ws = new WebSocket('wss://YOUR_DROPLET_IP:8080/terminal/test-session')
|
|
|
|
ws.onopen = () => {
|
|
console.log('Connected')
|
|
ws.send(JSON.stringify({ type: 'list_sessions' }))
|
|
}
|
|
|
|
ws.onmessage = (event) => {
|
|
console.log('Received:', JSON.parse(event.data))
|
|
}
|
|
```
|
|
|
|
### 3. Test Terminal Creation in Canvas
|
|
|
|
1. Open canvas dashboard
|
|
2. Click terminal button in toolbar
|
|
3. Should see session browser
|
|
4. Click "Create New Session" or attach to existing
|
|
5. Should see terminal prompt
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### WebSocket Connection Failed
|
|
|
|
**Check server is running:**
|
|
```bash
|
|
sudo systemctl status terminal-server
|
|
sudo journalctl -u terminal-server -f
|
|
```
|
|
|
|
**Check firewall:**
|
|
```bash
|
|
sudo ufw status
|
|
telnet YOUR_DROPLET_IP 8080
|
|
```
|
|
|
|
**Check nginx (if using):**
|
|
```bash
|
|
sudo nginx -t
|
|
sudo tail -f /var/log/nginx/error.log
|
|
```
|
|
|
|
### SSH Connection Failed
|
|
|
|
**Test SSH manually:**
|
|
```bash
|
|
ssh -i /opt/terminal-server/key canvas-terminal@localhost
|
|
```
|
|
|
|
**Check SSH key permissions:**
|
|
```bash
|
|
chmod 600 /opt/terminal-server/key
|
|
chown canvas-terminal:canvas-terminal /opt/terminal-server/key
|
|
```
|
|
|
|
**Check authorized_keys:**
|
|
```bash
|
|
cat /home/canvas-terminal/.ssh/authorized_keys
|
|
```
|
|
|
|
### tmux Commands Not Working
|
|
|
|
**Test tmux manually:**
|
|
```bash
|
|
tmux ls
|
|
tmux new-session -d -s test
|
|
tmux attach -t test
|
|
```
|
|
|
|
**Install tmux if missing:**
|
|
```bash
|
|
sudo apt update
|
|
sudo apt install tmux
|
|
```
|
|
|
|
### Browser Console Errors
|
|
|
|
**Mixed content (HTTP/HTTPS):**
|
|
- Ensure WebSocket uses `wss://` not `ws://`
|
|
- Use HTTPS for canvas dashboard
|
|
- Use SSL certificate for WebSocket server
|
|
|
|
**CORS errors:**
|
|
- Check nginx/server CORS headers
|
|
- Verify origin matches
|
|
|
|
---
|
|
|
|
## Security Hardening
|
|
|
|
### 1. Restrict SSH Key
|
|
|
|
Create dedicated key for terminal server:
|
|
|
|
```bash
|
|
ssh-keygen -t ed25519 -f /opt/terminal-server/key -N ""
|
|
```
|
|
|
|
Add to droplet's `authorized_keys` with command restriction:
|
|
|
|
```bash
|
|
command="/usr/bin/tmux" ssh-ed25519 AAAA... canvas-terminal
|
|
```
|
|
|
|
### 2. Use Restricted Shell
|
|
|
|
Edit `/home/canvas-terminal/.bashrc`:
|
|
|
|
```bash
|
|
# Only allow tmux
|
|
if [[ $- == *i* ]]; then
|
|
exec tmux attach || exec tmux
|
|
fi
|
|
```
|
|
|
|
### 3. Rate Limiting
|
|
|
|
Add to nginx config:
|
|
|
|
```nginx
|
|
limit_req_zone $binary_remote_addr zone=terminal:10m rate=10r/s;
|
|
|
|
server {
|
|
location / {
|
|
limit_req zone=terminal burst=20;
|
|
# ... proxy config ...
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4. Authentication
|
|
|
|
Add JWT validation in WebSocket server:
|
|
|
|
```javascript
|
|
import jwt from 'jsonwebtoken'
|
|
|
|
wss.on('connection', (ws, req) => {
|
|
const token = req.headers['authorization']?.split(' ')[1]
|
|
|
|
try {
|
|
const payload = jwt.verify(token, JWT_SECRET)
|
|
const userId = payload.userId
|
|
// ... rest of code ...
|
|
} catch (err) {
|
|
ws.close(1008, 'Unauthorized')
|
|
return
|
|
}
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
1. Choose Option 1 or Option 2
|
|
2. Set up backend server/routes
|
|
3. Configure SSH credentials
|
|
4. Test WebSocket connection
|
|
5. Test terminal creation in canvas
|
|
6. Add authentication
|
|
7. Deploy to production
|
|
|
|
---
|
|
|
|
## Additional Resources
|
|
|
|
- [ssh2 documentation](https://github.com/mscdex/ssh2)
|
|
- [ws (WebSocket) documentation](https://github.com/websockets/ws)
|
|
- [tmux manual](https://github.com/tmux/tmux/wiki)
|
|
- [Cloudflare Durable Objects](https://developers.cloudflare.com/durable-objects/)
|
|
- [nginx WebSocket proxying](https://nginx.org/en/docs/http/websocket.html)
|
|
|
|
---
|
|
|
|
**Last Updated:** 2025-01-19
|
|
**Status:** Implementation guide for terminal feature backend
|