Documentation

Comprehensive guides and references for StreamSpace

Overview

StreamSpace is a Kubernetes-native multi-user platform that streams containerized applications to web browsers using VNC technology. It provides on-demand provisioning with auto-hibernation for resource efficiency.

Key Concepts

• Session - A running instance of an application for a user
• Template - An application definition that can be launched as a Session
• Hibernation - Automatic scale-to-zero when sessions are idle
• Plugin - Extension that adds functionality to StreamSpace
• Repository - Git repository containing templates or plugins

Architecture

StreamSpace uses a multi-platform event-driven architecture with NATS messaging:

1. Platform Controllers

Platform-specific controllers that manage sessions on their respective infrastructure via NATS events.

• Kubernetes Controller (k8s-controller/) - Kubebuilder-based, manages CRDs
• Docker Controller (docker-controller/) - Manages Docker containers
• NATS JetStream for durable event delivery
• Prometheus metrics export

View detailed architecture →

2. API Backend

Go-based REST + WebSocket API using Gin framework.

• Session management endpoints
• Template catalog and repository sync
• Plugin management system
• PostgreSQL caching layer
• Connection tracking
• Real-time WebSocket updates

API Backend documentation →

3. Web UI

React + TypeScript web interface with Material-UI.

• User dashboard and session management
• Template catalog browser
• Plugin catalog and management
• Admin panel for users, groups, quotas
• Real-time updates via WebSocket

UI documentation →

Installation

See the Getting Started guide for detailed installation instructions.

Quick Install

# Clone repository
git clone https://github.com/JoshuaAFerguson/streamspace.git
cd streamspace

# Install with Helm
helm install streamspace ./chart \\
  --namespace streamspace \\
  --create-namespace

Usage

Creating Sessions

Sessions can be created via the Web UI, kubectl, or API.

Using kubectl

kubectl apply -f - <

curl -X POST http://api.streamspace.local/api/v1/sessions \\
  -H "Authorization: Bearer $TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{
    "user": "user1",
    "template": "firefox-browser",
    "state": "running",
    "resources": {
      "memory": "2Gi",
      "cpu": "1000m"
    }
  }'

# List sessions
kubectl get sessions -n streamspace

# Get session details
kubectl describe session user1-firefox -n streamspace

# Hibernate a session
kubectl patch session user1-firefox -n streamspace \\
  --type merge -p '{"spec":{"state":"hibernated"}}'

# Wake a session
kubectl patch session user1-firefox -n streamspace \\
  --type merge -p '{"spec":{"state":"running"}}'

# Delete a session
kubectl delete session user1-firefox -n streamspace

cd k8s-controller

# Run locally
make run

# Run tests
make test

# Build Docker image
make docker-build IMG=myregistry/streamspace-kubernetes-controller:dev

cd docker-controller

# Build locally
go build -o streamspace-docker-controller

# Run with Docker Compose
./scripts/docker-dev.sh

# Test NATS connectivity
./scripts/test-nats.sh

cd api

# Run locally
go run cmd/main.go

# Run tests
go test ./...

cd ui

# Install dependencies
npm install

# Run development server
npm run dev

# Build for production
npm run build

controller:
  replicaCount: 3
  leaderElection:
    enabled: true
  resources:
    requests:
      memory: 512Mi
      cpu: 500m

api:
  replicaCount: 3
  autoscaling:
    enabled: true
    minReplicas: 3
    maxReplicas: 10

ui:
  replicaCount: 2

postgresql:
  enabled: false
  external:
    enabled: true
    host: "postgres.example.com"

ingress:
  enabled: true
  className: "nginx"
  tls:
    enabled: true
    secretName: "streamspace-tls"

monitoring:
  enabled: true