Merge branch 'main' into fix-orchestrator-dns-names

westbrook-ai · web-flow · commit e474360dcc4a · 2026-04-02T20:47:07.000-06:00
diff --git a/.github/workflows/docker-build.yml b/.github/workflows/docker-build.yml
@@ -12,8 +12,24 @@ env:
   REGISTRY: ghcr.io
 
 jobs:
+  get-version:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Extract version from pyproject.toml
+        id: version
+        run: |
+          VERSION=$(grep '^version' pyproject.toml | head -1 | sed 's/version = "\(.*\)"/\1/')
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Extracted version: $VERSION"
+
   build-orchestrator:
     runs-on: ${{ matrix.runner }}
+    needs: [get-version]
     permissions:
       contents: read
       packages: write
@@ -63,6 +79,7 @@ jobs:
             type=sha,prefix=git-
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=${{ needs.get-version.outputs.version }}
           flavor: |
             latest=${{ github.ref == 'refs/heads/main' }}
 
@@ -109,6 +126,7 @@ jobs:
 
   build-operator:
     runs-on: ${{ matrix.runner }}
+    needs: [get-version]
     permissions:
       contents: read
       packages: write
@@ -158,6 +176,7 @@ jobs:
             type=sha,prefix=git-
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=${{ needs.get-version.outputs.version }}
           flavor: |
             latest=${{ github.ref == 'refs/heads/main' }}
 
@@ -204,7 +223,7 @@ jobs:
 
   merge-orchestrator-images:
     runs-on: ubuntu-latest
-    needs: [build-orchestrator]
+    needs: [get-version, build-orchestrator]
     permissions:
       contents: read
       packages: write
@@ -241,6 +260,7 @@ jobs:
             type=sha,prefix=git-
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=${{ needs.get-version.outputs.version }}
           flavor: |
             latest=${{ github.ref == 'refs/heads/main' }}
 
@@ -252,11 +272,11 @@ jobs:
 
       - name: Inspect image
         run: |
-          docker buildx imagetools inspect ${{ env.FULL_IMAGE_NAME }}:${{ steps.meta.outputs.version }}
+          docker buildx imagetools inspect ${{ env.FULL_IMAGE_NAME }}:${{ needs.get-version.outputs.version }}
 
   merge-operator-images:
     runs-on: ubuntu-latest
-    needs: [build-operator]
+    needs: [get-version, build-operator]
     permissions:
       contents: read
       packages: write
@@ -293,6 +313,7 @@ jobs:
             type=sha,prefix=git-
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=${{ needs.get-version.outputs.version }}
           flavor: |
             latest=${{ github.ref == 'refs/heads/main' }}
 
@@ -304,4 +325,33 @@ jobs:
 
       - name: Inspect image
         run: |
-          docker buildx imagetools inspect ${{ env.FULL_IMAGE_NAME }}:${{ steps.meta.outputs.version }}
+          docker buildx imagetools inspect ${{ env.FULL_IMAGE_NAME }}:${{ needs.get-version.outputs.version }}
+
+  create-release:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    needs: [get-version, merge-orchestrator-images, merge-operator-images]
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Extract changelog for version
+        id: changelog
+        run: |
+          VERSION="${{ needs.get-version.outputs.version }}"
+          # Extract the section for this version from CHANGELOG.md
+          NOTES=$(awk "/^## \\[$VERSION\\]/{found=1; next} /^## \\[/{if(found) exit} found" CHANGELOG.md)
+          # Write to file to preserve newlines
+          echo "$NOTES" > /tmp/release-notes.md
+          echo "Extracted release notes for v$VERSION"
+          cat /tmp/release-notes.md
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ needs.get-version.outputs.version }}
+          name: v${{ needs.get-version.outputs.version }}
+          body_path: /tmp/release-notes.md
+          make_latest: true
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] - 2026-04-02
+
+### Added
+- Multi-tenant terminal orchestrator with Docker and Kubernetes backends.
+- Kubernetes operator for terminal custom resource management.
+- CLI interface for managing terminals.
+- Docker build workflows for orchestrator and operator images (multi-arch: amd64/arm64).
diff --git a/README.md b/README.md
@@ -5,32 +5,21 @@
 
 Per-user [Open Terminal](https://github.com/open-webui/open-terminal) orchestration for Docker and Kubernetes.
 
-Giving terminal access to users on Open WebUI requires per-user isolation: separate containers, each with their own credentials and resource constraints. Terminals handles the full lifecycle: provisioning containers on demand, proxying traffic per user, enforcing resource and network policies, validating Open WebUI JWTs natively, and cleaning up idle instances.
-
-| Capability | |
-|---|---|
-| **Backends** | Docker, Kubernetes, K8s Operator |
-| **Provisioning** | On-demand per user, transparent to the client |
-| **Policies** | Per-environment image, CPU, memory, network, env vars via REST API |
-| **Auth** | Open WebUI JWT validation or static API key |
-| **Hard caps** | Admin-enforced limits on CPU, memory, storage, and allowed images |
-| **Multi-environment** | Named policies with routing via `/p/{policy_id}/` |
-| **Network control** | Egress filtering via `env.OPEN_TERMINAL_ALLOWED_DOMAINS` |
-| **Idle cleanup** | Automatic teardown of inactive instances |
-| **Runtime changes** | Update policies via API without redeployment |
+Terminals gives every Open WebUI user their own isolated container — with separate credentials, resource limits, and network rules. It handles the full lifecycle automatically: spinning up containers when a user connects, proxying traffic, enforcing limits, and cleaning up when they're done.
+
+```
+Open WebUI  →  Terminals service  →  per-user containers
+               (this project)        (Open Terminal images)
+```
 
 > [!IMPORTANT]
 > **Production use requires an [Open WebUI Enterprise License](LICENSE) with Terminals access.** Contact the Open WebUI team to get started.
 
-
 ## Quick Start
 
-```bash
-pip install -e .
-terminals serve
-```
+The fastest way to get running is with Docker. Terminals will manage sibling containers through the Docker socket.
 
-Or with Docker:
+### Docker (recommended for single-node)
 
 ```bash
 docker run -p 3000:3000 \
@@ -39,24 +28,61 @@ docker run -p 3000:3000 \
   terminals
 ```
 
+**Prerequisites:** Docker running on the host.
+
+### Kubernetes Operator (recommended for clusters)
+
+For Kubernetes deployments, the operator manages `Terminal` custom resources automatically — handling pod creation, storage, and cleanup through CRDs.
+
+```bash
+# Install the CRD and operator
+kubectl apply -f manifests/terminal-crd.yaml
+kubectl apply -f manifests/operator-deployment.yaml
+```
+
+Set `TERMINALS_BACKEND=kubernetes-operator` when deploying the Terminals service.
+
+### From source (development)
+
+```bash
+pip install -e .
+terminals serve
+```
+
+## Choosing a Backend
+
+| Backend | Best for | How it works |
+|---------|----------|-------------|
+| `docker` | Single-node, local dev | One container per user via Docker socket |
+| `kubernetes-operator` | Production K8s clusters | Operator watches `Terminal` CRDs for automated lifecycle |
+| `kubernetes` | K8s without CRDs | Direct Pod + PVC + Service per user (you manage resources) |
+
+Set the backend with `TERMINALS_BACKEND` (defaults to `docker`).
+
 ## Policies
 
-Policies define per-environment configuration. Manage via REST API:
+Policies let you define different environments — for example, a "data-science" environment with extra CPU and specific Python packages, or a "sandbox" environment with restricted network access.
+
+Without any policies, Terminals uses the defaults from your configuration. Once you're ready to customize, manage policies through the REST API:
 
 ```bash
+# Create a "data-science" policy
 curl -X PUT http://localhost:3000/api/v1/policies/data-science \
   -H "Authorization: Bearer $API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
     "image": "ghcr.io/open-webui/open-terminal:python-ds",
     "cpu_limit": "2",
     "memory_limit": "4Gi",
-    "env": {"OPENAI_API_KEY": "sk-proj-...", "OPEN_TERMINAL_ALLOWED_DOMAINS": "*.pypi.org,github.com"},
+    "env": {
+      "OPENAI_API_KEY": "sk-proj-...",
+      "OPEN_TERMINAL_ALLOWED_DOMAINS": "*.pypi.org,github.com"
+    },
     "idle_timeout_minutes": 30
   }'
 ```
 
-Route requests through a policy via `/p/{policy_id}/`:
+Route requests through a policy by adding `/p/{policy_id}/` to the URL:
 
 ```bash
 curl -X POST http://localhost:3000/p/data-science/execute \
@@ -65,47 +91,41 @@ curl -X POST http://localhost:3000/p/data-science/execute \
   -d '{"command": "echo hello"}'
 ```
 
+### Policy fields
+
 | Field | Type | Description |
 |-------|------|-------------|
-| `image` | string | Container image |
-| `env` | dict | Environment variables |
+| `image` | string | Container image to use |
+| `env` | dict | Environment variables passed to the container |
 | `cpu_limit` | string | Max CPU (e.g. `"2"`) |
 | `memory_limit` | string | Max memory (e.g. `"4Gi"`) |
-| `storage` | string | Persistent volume size (absent = ephemeral) |
-| `storage_mode` | string | `per-user`, `shared`, `shared-rwo` (absent = global default) |
-| `idle_timeout_minutes` | int | Idle timeout before cleanup |
+| `storage` | string | Persistent volume size (omit for ephemeral storage) |
+| `storage_mode` | string | `per-user`, `shared`, or `shared-rwo` |
+| `idle_timeout_minutes` | int | Minutes of inactivity before the container is cleaned up |
 
 ## Configuration
 
-Environment variables prefixed with `TERMINALS_` (or `.env` file).
+All settings are configured through environment variables prefixed with `TERMINALS_`, or via a `.env` file.
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `TERMINALS_BACKEND` | `docker` | `docker`, `kubernetes`, `kubernetes-operator` |
-| `TERMINALS_API_KEY` | *(auto)* | Bearer token for API auth |
-| `TERMINALS_OPEN_WEBUI_URL` | | Open WebUI URL for JWT auth |
+| `TERMINALS_BACKEND` | `docker` | `docker`, `kubernetes`, or `kubernetes-operator` |
+| `TERMINALS_API_KEY` | *(auto-generated)* | Bearer token for API auth |
 | `TERMINALS_IMAGE` | `ghcr.io/open-webui/open-terminal:latest` | Default container image |
-| `TERMINALS_MAX_CPU` | | Hard cap on CPU |
-| `TERMINALS_MAX_MEMORY` | | Hard cap on memory |
-| `TERMINALS_MAX_STORAGE` | | Hard cap on storage |
-| `TERMINALS_ALLOWED_IMAGES` | | Comma-separated image globs |
-| `TERMINALS_KUBERNETES_STORAGE_MODE` | `per-user` | `per-user`, `shared`, `shared-rwo` |
+| `TERMINALS_MAX_CPU` | | Hard cap on CPU per container |
+| `TERMINALS_MAX_MEMORY` | | Hard cap on memory per container |
+| `TERMINALS_MAX_STORAGE` | | Hard cap on storage per container |
+| `TERMINALS_ALLOWED_IMAGES` | | Comma-separated list of allowed image patterns |
+| `TERMINALS_KUBERNETES_STORAGE_MODE` | `per-user` | `per-user`, `shared`, or `shared-rwo` |
 
 See [`config.py`](terminals/config.py) for the full list.
 
 ## Authentication
 
-| Mode | Trigger |
-|------|---------|
-| **Open WebUI JWT** | Set `TERMINALS_OPEN_WEBUI_URL` |
-| **API Key** | Set `TERMINALS_API_KEY` |
-| **Open** | Neither set (dev only) |
-
-## Backends
-
-- **`docker`** – One container per user via Docker socket
-- **`kubernetes`** – Pod + PVC + Service per user
-- **`kubernetes-operator`** – Kopf operator watching `Terminal` CRDs
+| Mode | How to enable |
+|------|---------------|
+| **API Key** | Set `TERMINALS_API_KEY` to a static token |
+| **Open (dev only)** | Leave unset — no auth, for local development only |
 
 ## License
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "terminals"
-version = "0.1.1"
+version = "0.0.2"
 description = "Multi-tenant terminal orchestrator for Open Terminal."
 readme = "README.md"
 authors = [
