docs: add terminal API and user documentation
- Add docs/api/terminal.md with WebSocket protocol and reset endpoint - Add docs/features/terminal.md with user guide for persistent sessions - Add docs/features/terminal-troubleshooting.md with diagnostic steps - Mark tasks 8.1-8.3 complete Refs: persistent-terminal-sessions tasks 8.x
This commit is contained in:
@@ -0,0 +1,172 @@
|
||||
# Terminal Troubleshooting Guide
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Cannot Connect to Terminal
|
||||
|
||||
**Symptom:** Terminal shows "Connection closed" or "Error" status immediately.
|
||||
|
||||
**Solutions:**
|
||||
1. Verify the tool instance is running:
|
||||
- Check instance status in the UI
|
||||
- Start the instance if it's stopped
|
||||
|
||||
2. Check browser console for errors:
|
||||
- Open browser DevTools (F12)
|
||||
- Look for WebSocket connection errors
|
||||
- Check for CORS or authentication errors
|
||||
|
||||
3. Verify network connectivity:
|
||||
- Ensure you can reach the API server
|
||||
- Check if WebSocket connections are blocked by firewall/proxy
|
||||
- Try accessing from a different network
|
||||
|
||||
**If the issue persists:**
|
||||
- Reset the terminal session
|
||||
- Refresh the page
|
||||
- Check server logs for errors
|
||||
|
||||
### Terminal Freezes or Becomes Unresponsive
|
||||
|
||||
**Symptom:** Terminal accepts no input or stops updating.
|
||||
|
||||
**Solutions:**
|
||||
1. **Reset the terminal:**
|
||||
- Click the Reset button in the terminal header
|
||||
- Confirm the reset action
|
||||
- Wait for the new session to start
|
||||
|
||||
2. **Check for stuck processes:**
|
||||
- Try Ctrl+C to interrupt any running process
|
||||
- If that doesn't work, reset the terminal
|
||||
|
||||
3. **Browser issues:**
|
||||
- Close and reopen the browser tab
|
||||
- Clear browser cache and cookies
|
||||
- Try a different browser
|
||||
|
||||
### Output Not Showing
|
||||
|
||||
**Symptom:** Commands execute but no output appears.
|
||||
|
||||
**Solutions:**
|
||||
1. Check terminal focus:
|
||||
- Click inside the terminal area
|
||||
- Look for the cursor indicator
|
||||
|
||||
2. Resize the terminal:
|
||||
- The terminal may need a resize event to render properly
|
||||
- Try resizing the browser window slightly
|
||||
|
||||
3. Reset the terminal session
|
||||
|
||||
### Reconnection Loop
|
||||
|
||||
**Symptom:** Terminal keeps disconnecting and reconnecting repeatedly.
|
||||
|
||||
**Solutions:**
|
||||
1. Check instance health:
|
||||
- The instance may be unhealthy or restarting
|
||||
- Check instance logs for errors
|
||||
|
||||
2. Network stability:
|
||||
- Unstable network causes repeated disconnections
|
||||
- Try on a more stable connection
|
||||
|
||||
3. Multiple tabs:
|
||||
- Only one tab can connect to a terminal session
|
||||
- Close other tabs with the same terminal open
|
||||
|
||||
## Diagnostic Steps
|
||||
|
||||
### Check WebSocket Connection
|
||||
|
||||
1. Open browser DevTools (F12)
|
||||
2. Go to Network tab
|
||||
3. Filter by "WS" (WebSocket)
|
||||
4. Look for the terminal WebSocket connection
|
||||
5. Check:
|
||||
- Connection status (should be 101 Switching Protocols)
|
||||
- Messages tab for ping/pong traffic
|
||||
- Any error messages in the connection
|
||||
|
||||
### Verify Terminal Session
|
||||
|
||||
To check if a terminal session exists on the server:
|
||||
|
||||
```bash
|
||||
# Check server logs for session activity
|
||||
docker logs hq-api | grep -i "terminal"
|
||||
```
|
||||
|
||||
Look for:
|
||||
- "Terminal session ready" - session created successfully
|
||||
- "Reattaching to existing terminal session" - reconnecting to existing session
|
||||
- "Cleaning up idle terminal session" - session expired
|
||||
|
||||
### Test Basic Connectivity
|
||||
|
||||
```bash
|
||||
# Test if the WebSocket endpoint is reachable
|
||||
curl -i -N \
|
||||
-H "Connection: Upgrade" \
|
||||
-H "Upgrade: websocket" \
|
||||
-H "Sec-WebSocket-Key: test" \
|
||||
-H "Sec-WebSocket-Version: 13" \
|
||||
https://your-api-domain/ws/tool-instances/test/terminal
|
||||
```
|
||||
|
||||
Expected: HTTP 400 (invalid instance ID) or redirect to auth
|
||||
|
||||
## Error Codes
|
||||
|
||||
### WebSocket Close Codes
|
||||
|
||||
- **1000**: Normal closure - connection closed cleanly
|
||||
- **4000**: Generic error - check server logs
|
||||
- **4001**: Invalid instance ID - verify the instance exists
|
||||
- **4003**: Unauthorized - session expired or invalid
|
||||
- **4004**: Instance not running - start the instance first
|
||||
|
||||
### HTTP Status Codes
|
||||
|
||||
- **404**: Instance not found - verify instance ID
|
||||
- **400**: Instance not running - start the instance
|
||||
- **500**: Server error - check server logs
|
||||
|
||||
## Resetting Everything
|
||||
|
||||
If all else fails:
|
||||
|
||||
1. **Reset terminal session:**
|
||||
```
|
||||
POST /api/projects/{project_id}/repositories/{repo_id}/instances/{instance_id}/terminal/reset
|
||||
```
|
||||
|
||||
2. **Restart the tool instance:**
|
||||
- Stop the instance
|
||||
- Start the instance again
|
||||
- Reconnect to the terminal
|
||||
|
||||
3. **Clear browser data:**
|
||||
- Clear cookies for the domain
|
||||
- Clear local storage
|
||||
- Hard refresh the page (Ctrl+F5)
|
||||
|
||||
## Getting Help
|
||||
|
||||
If issues persist:
|
||||
|
||||
1. Collect diagnostic information:
|
||||
- Browser console logs
|
||||
- Network tab WebSocket messages
|
||||
- Server logs (`docker logs hq-api`)
|
||||
- Instance status and health
|
||||
|
||||
2. Check the [Terminal API documentation](/docs/api/terminal.md) for protocol details
|
||||
|
||||
3. Report issues with:
|
||||
- Steps to reproduce
|
||||
- Expected vs actual behavior
|
||||
- Browser and OS version
|
||||
- Instance type and configuration
|
||||
@@ -0,0 +1,83 @@
|
||||
# Terminal Sessions
|
||||
|
||||
Terminal sessions provide interactive shell access to your running tool instances directly in the browser.
|
||||
|
||||
## Persistent Sessions
|
||||
|
||||
Terminal sessions are **persistent** - they survive browser refreshes, network interruptions, and tab switches.
|
||||
|
||||
### How It Works
|
||||
|
||||
- When you open a terminal, a shell session starts inside the tool instance container
|
||||
- If you close the browser or lose connection, the session keeps running
|
||||
- When you reconnect, you reattach to the same session with all previous output preserved
|
||||
- Sessions automatically clean up after 30 minutes of inactivity
|
||||
|
||||
### Reconnecting
|
||||
|
||||
If your connection drops:
|
||||
1. The terminal shows "Reconnecting..." status
|
||||
2. The client automatically attempts to reconnect with exponential backoff
|
||||
3. On successful reconnection, buffered output is replayed
|
||||
4. You can continue working where you left off
|
||||
|
||||
## Resetting the Terminal
|
||||
|
||||
If your terminal becomes unresponsive or you want a fresh start:
|
||||
|
||||
1. Click the **Reset** button in the terminal header
|
||||
2. Confirm the reset action
|
||||
3. The current shell is killed and a new one starts
|
||||
4. All terminal history is cleared
|
||||
|
||||
**Note:** Resetting only affects the terminal session, not the tool instance itself. Any files you've created remain intact.
|
||||
|
||||
## Mobile Terminal
|
||||
|
||||
On mobile devices, the terminal includes:
|
||||
- Special keys panel (Ctrl, Alt, Tab, arrows, etc.)
|
||||
- Font size controls
|
||||
- Auto-hiding header for maximum screen space
|
||||
- Touch-friendly interface
|
||||
|
||||
## Keyboard Shortcuts
|
||||
|
||||
Standard terminal shortcuts work as expected:
|
||||
- `Ctrl+C`: Send interrupt signal
|
||||
- `Ctrl+D`: Send EOF (close shell if empty)
|
||||
- `Ctrl+L`: Clear screen
|
||||
- `Ctrl+Z`: Suspend process
|
||||
|
||||
Special keys can be accessed via the special keys panel on mobile or by using modifier combinations.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Connection Issues
|
||||
|
||||
**"Connection closed" error:**
|
||||
- The tool instance may have stopped - check the instance status
|
||||
- Network issues - the client will auto-reconnect
|
||||
- Session timeout - sessions expire after 30 minutes of inactivity
|
||||
|
||||
**Terminal not responding:**
|
||||
- Try resetting the terminal using the Reset button
|
||||
- Check if the tool instance is still running
|
||||
- Refresh the page to force reconnection
|
||||
|
||||
### Display Issues
|
||||
|
||||
**Text not visible:**
|
||||
- Adjust font size using +/- buttons
|
||||
- Check if the terminal has focus (click inside it)
|
||||
- Try resizing the browser window
|
||||
|
||||
**Characters not appearing:**
|
||||
- Ensure the terminal has focus
|
||||
- Check if a modifier key is stuck (Ctrl, Alt)
|
||||
- Reset the terminal if stuck
|
||||
|
||||
## Session Limits
|
||||
|
||||
- **One connection per terminal:** Only one browser tab can connect to a terminal session at a time. Opening a new connection closes the old one.
|
||||
- **30-minute idle timeout:** Sessions without activity are automatically cleaned up
|
||||
- **Buffer size:** Up to 10KB of output is buffered for replay on reconnection
|
||||
Reference in New Issue
Block a user