Skip to content

README.md

Latest commit

 

History

History
85 lines (65 loc) · 3.24 KB

README.md

File metadata and controls

85 lines (65 loc) · 3.24 KB

HackTerm Backend

A production-ready Go backend for HackTerm that provides Kubernetes-based terminal sessions via WebSocket connections.

Features

  • Kubernetes Integration: Automatic pod creation and management for terminal sessions
  • Auto-Setup: Automatically installs Kubernetes (K3s) on VPS if not present
  • Production Ready: Comprehensive logging, security headers, resource limits, and CORS protection
  • WebSocket Support: Real-time terminal I/O via WebSocket connections
  • Resource Management: Configurable CPU/memory limits and automatic cleanup
  • Security: Production-safe CORS, input validation, and security headers

Quick Start - VPS Deployment

  1. Upload and run installation:
scp -r . user@your-vps:/tmp/hackterm-backend
ssh user@your-vps 'cd /tmp/hackterm-backend && sudo ./deploy/install.sh'
  1. Configure for your domain:
sudo nano /opt/hackterm/.env
# Update HACKTERM_ALLOWED_ORIGINS with your frontend domain
  1. Start the service:
sudo systemctl start hackterm && sudo systemctl enable hackterm

The backend will be available on port 10128 and automatically set up Kubernetes if needed.

Configuration

Key environment variables (see deploy/production.env):

  • GO_ENV=production - Enables production mode with port 10128
  • HACKTERM_AUTO_SETUP=true - Auto-installs Kubernetes (K3s) with dedicated namespace and RBAC
  • HACKTERM_ALLOWED_ORIGINS - Comma-separated CORS origins
  • HACKTERM_CPU_LIMIT/MEMORY_LIMIT - Resource limits per terminal pod
  • HACKTERM_MAX_PODS=20 - Maximum concurrent terminals

API Endpoints

  • POST /api/terminal/start - Start new terminal session
  • WS /ws/terminal/{sessionId} - WebSocket terminal I/O
  • GET /health - Health check
  • GET /metrics - Application metrics

Security Features

� Production-safe CORS with configurable origins
� Input validation and UUID verification
� Resource limits and pod security contexts
� Comprehensive structured logging
� Automatic cleanup of expired pods
� Security headers and CSP

The backend automatically switches between development (permissive) and production (secure) modes based on GO_ENV.

Port Configuration Summary

  • Backend API/WebSocket: Port 10128 (your Flutter app connects here)
  • Kubernetes API: Port 6443 (internal, auto-configured)
  • SSH: Port 22 (maintained for remote access)
  • Container Registry: Uses Docker Hub for terminal images
  • Terminal Pods: Run in dedicated hackterm namespace with resource limits

Firewall (UFW) Configuration

The auto-setup configures UFW with secure defaults:

  • ✅ Allow: SSH (22), HackTerm (10128), Kubernetes API (6443)
  • ✅ Allow: Kubernetes internal ports (kubelet, etcd, scheduler)
  • ✅ Allow: Docker/CNI network interfaces (container communication)
  • ✅ Rate limiting: Port 10128 to prevent abuse
  • 🚫 Deny: All other incoming traffic by default

When you set GO_ENV=production, the backend will:

  1. Listen on port 10128 for Flutter connections
  2. Auto-install K3s if Kubernetes not found
  3. Create hackterm namespace for terminal isolation
  4. Set up RBAC permissions for pod management
  5. Configure UFW firewall with secure defaults
  6. Apply production security (strict CORS, resource limits)