Features/database persistence

.env.example

@@ -0,0 +1,40 @@
+# =============================================================================
+# Helios Platform - Environment Variables
+# =============================================================================
+# Copy this file to .env and fill in your values:
+#   cp .env.example .env
+#
+# This single .env at the repo root is the source of truth for all credentials.
+# The Taskfile distributes these to operator and portal contexts automatically.
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# GitHub Integration (required)
+# -----------------------------------------------------------------------------
+# Personal Access Token with 'repo' and 'workflow' scopes
+GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+GITHUB_USER=your-github-username
+GITHUB_ORG=helios-platform-team
+
+# -----------------------------------------------------------------------------
+# GitHub OAuth App (required for portal login)
+# -----------------------------------------------------------------------------
+# Create an OAuth App at https://github.com/settings/developers
+# Homepage URL: http://localhost:3000
+# Callback URL:  http://localhost:7007/api/auth/github/handler/frame
+AUTH_GITHUB_CLIENT_ID=
+AUTH_GITHUB_CLIENT_SECRET=
+
+# -----------------------------------------------------------------------------
+# Docker Registry (required for Tekton pipelines)
+# -----------------------------------------------------------------------------
+DOCKER_SERVER=https://index.docker.io/v1/
+DOCKER_USERNAME=
+DOCKER_PASSWORD=
+DOCKER_EMAIL=
+
+# -----------------------------------------------------------------------------
+# Git Author (optional, used by operator for GitOps commits)
+# -----------------------------------------------------------------------------
+GIT_AUTHOR_NAME="Helios Operator"
+GIT_AUTHOR_EMAIL=operator@helios.io

.github/workflows/operator-ci.yml

@@ -11,7 +11,7 @@ on:
   pull_request:
     branches:
       - main
-      - 'features/*'
+      - "features/*"
 
 jobs:
   test:
@@ -23,12 +23,12 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Go
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@v6
         with:
-          go-version: '1.26'
+          go-version: "1.26"
           cache-dependency-path: apps/operator/go.sum
 
       - name: Run tests

.github/workflows/portal-ci.yml

@@ -19,12 +19,12 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
-          node-version: "22"
+          node-version: "24"
           cache: "yarn"
           cache-dependency-path: "apps/portal/yarn.lock"
 

.gitignore

@@ -1,3 +1,14 @@
 # SQLite
 *.sqlite
 apps/portal/packages/backend/*.sqlite
+
+# Environment secrets
+.env
+.env.*
+**/.env
+**/.env.*
+!.env.example
+!**/.env.example
+
+# Claude
+.claude/

Taskfile.yml

@@ -0,0 +1,290 @@
+# =============================================================================
+# Helios Platform - Root Taskfile
+# =============================================================================
+# Usage:
+#   task check          Verify all prerequisites are installed
+#   task setup          Bootstrap the full local environment (cluster + deps)
+#   task dev            Run operator + portal concurrently
+#   task test           Run all tests
+#   task clean          Tear down the k3d cluster
+#
+# First-time setup:
+#   cp .env.example .env   # fill in your credentials
+#   task setup             # ~5-10 minutes
+#   task dev               # opens operator + portal
+#
+# Cross-platform:
+#   Linux/macOS: works natively
+#   Windows:     requires Git Bash or WSL (for bash-based sub-scripts)
+# =============================================================================
+version: '3'
+
+dotenv: ['.env']
+
+vars:
+  CLUSTER_NAME: helios-dev
+  ARGOCD_PORT: '8080'
+  KUBECTL_PROXY_PORT: '8001'
+
+set: [errexit, pipefail]
+
+# =============================================================================
+# Prerequisite Checking
+# =============================================================================
+tasks:
+  check:
+    desc: Verify all development prerequisites are installed
+    cmds:
+      - cmd: bash scripts/check-prereqs.sh
+        platforms: [linux, darwin]
+      - cmd: cmd /c scripts\\check-prereqs.bat
+        platforms: [windows]
+
+  check:env:
+    desc: Verify prerequisites and .env configuration
+    cmds:
+      - cmd: bash scripts/check-prereqs.sh --env
+        platforms: [linux, darwin]
+      - cmd: cmd /c scripts\\check-prereqs.bat --env
+        platforms: [windows]
+
+  # ===========================================================================
+  # Setup Tasks
+  # ===========================================================================
+  setup:
+    desc: Bootstrap the full local development environment
+    deps: [check:env]
+    cmds:
+      - task: setup:cluster
+      - task: setup:tekton
+      - task: setup:argocd
+      - task: setup:crds
+      - task: setup:tekton-rbac
+      - task: setup:credentials
+      - task: setup:portal-deps
+      - echo ""
+      - echo "============================================="
+      - echo "  Helios local environment is ready!"
+      - echo "  Run 'task dev' to start developing."
+      - echo "============================================="
+
+  setup:cluster:
+    desc: Create a k3d cluster (idempotent)
+    status:
+      - k3d cluster list 2>/dev/null | grep -q '{{.CLUSTER_NAME}}'
+    cmds:
+      - echo "Creating k3d cluster '{{.CLUSTER_NAME}}'..."
+      - k3d cluster create {{.CLUSTER_NAME}} --agents 1 --wait --api-port 0.0.0.0:6550
+      - kubectl config set-cluster k3d-{{.CLUSTER_NAME}} --server=https://localhost:6550
+      - kubectl cluster-info
+
+  setup:tekton:
+    desc: Install Tekton Pipeline, Triggers, and Interceptors
+    cmds:
+      - echo "Installing Tekton Pipeline..."
+      - kubectl apply --filename https://storage.googleapis.com/tekton-releases/pipeline/latest/release.yaml
+      - echo "Installing Tekton Triggers..."
+      - kubectl apply --filename https://storage.googleapis.com/tekton-releases/triggers/latest/release.yaml
+      - echo "Installing Tekton Interceptors..."
+      - kubectl apply --filename https://storage.googleapis.com/tekton-releases/triggers/latest/interceptors.yaml
+      - echo "Waiting for Tekton Pipelines controller..."
+      - kubectl rollout status deployment/tekton-pipelines-controller -n tekton-pipelines --timeout=600s
+      - echo "Waiting for Tekton Pipelines webhook..."
+      - kubectl rollout status deployment/tekton-pipelines-webhook -n tekton-pipelines --timeout=600s
+      - echo "Waiting for webhook endpoints to register..."
+      - cmd: sleep 10
+        platforms: [linux, darwin]
+      - cmd: powershell -Command "Start-Sleep -Seconds 10"
+        platforms: [windows]
+      - echo "Patching Tekton feature flags..."
+      - >-
+        kubectl patch configmap feature-flags -n tekton-pipelines
+        -p '{"data":{"disable-affinity-assistant":"true","coschedule":"disabled"}}'
+      - kubectl rollout restart deployment tekton-pipelines-controller -n tekton-pipelines
+      - kubectl rollout status deployment/tekton-pipelines-controller -n tekton-pipelines --timeout=600s
+
+  setup:argocd:
+    desc: Install ArgoCD
+    cmds:
+      - kubectl create namespace argocd --dry-run=client -o yaml | kubectl apply -f -
+      - echo "Installing ArgoCD..."
+      - kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
+      - echo "Waiting for ArgoCD server..."
+      - kubectl rollout status deployment/argocd-server -n argocd --timeout=600s
+
+  setup:crds:
+    desc: Install Helios CRDs into the cluster
+    dir: apps/operator
+    cmds:
+      - cmd: make install
+        platforms: [linux, darwin]
+      - cmd: kubectl kustomize config/crd | kubectl apply -f -
+        platforms: [windows]
+
+  setup:tekton-rbac:
+    desc: Grant Tekton Triggers SA the permissions to create PipelineRuns
+    cmds:
+      - >-
+        kubectl create clusterrolebinding tekton-triggers-sa-admin
+        --clusterrole=cluster-admin
+        --serviceaccount=default:tekton-triggers-sa
+        --dry-run=client -o yaml | kubectl apply -f -
+
+  setup:credentials:
+    desc: Create Docker registry secret and link to pipeline SA
+    preconditions:
+      - sh: '[ -n "$DOCKER_USERNAME" ]'
+        msg: "DOCKER_USERNAME is not set in .env"
+      - sh: '[ -n "$DOCKER_PASSWORD" ]'
+        msg: "DOCKER_PASSWORD is not set in .env"
+    cmds:
+      - >-
+        kubectl create secret docker-registry docker-credentials
+        --docker-server=${DOCKER_SERVER:-https://index.docker.io/v1/}
+        --docker-username=$DOCKER_USERNAME
+        --docker-password=$DOCKER_PASSWORD
+        --docker-email=${DOCKER_EMAIL:-dev@helios.io}
+        --dry-run=client -o yaml | kubectl apply -f -
+      - >-
+        kubectl patch sa pipeline
+        -p '{"secrets": [{"name": "docker-credentials"}]}'
+        2>/dev/null || true
+
+  setup:portal-deps:
+    desc: Install Backstage portal dependencies
+    dir: apps/portal
+    cmds:
+      - yarn install
+
+  # ===========================================================================
+  # Development Tasks
+  # ===========================================================================
+  dev:
+    desc: Run operator and portal concurrently
+    deps: [dev:operator, dev:portal]
+
+  dev:operator:
+    desc: Run the Helios operator locally
+    dir: apps/operator
+    env:
+      HELIOS_CUE_PATH: '{{.ROOT_DIR}}/cue'
+      GITHUB_TOKEN: $GITHUB_TOKEN
+      GITHUB_USER: $GITHUB_USER
+    cmds:
+      - cmd: make run
+        platforms: [linux, darwin]
+      - cmd: go run ./cmd/main.go
+        platforms: [windows]
+
+  dev:portal:
+    desc: Run the Backstage portal with ArgoCD + kubectl proxy
+    dir: apps/portal
+    env:
+      AUTH_GITHUB_CLIENT_ID: $AUTH_GITHUB_CLIENT_ID
+      AUTH_GITHUB_CLIENT_SECRET: $AUTH_GITHUB_CLIENT_SECRET
+      GITHUB_TOKEN: $GITHUB_TOKEN
+      GITHUB_ORG: $GITHUB_ORG
+    cmds:
+      - task: dev:portal:proxy
+      - task: dev:portal:start
+
+  dev:portal:proxy:
+    desc: Start kubectl proxy and ArgoCD port-forward
+    internal: true
+    cmds:
+      - echo "Starting ArgoCD port-forward (localhost:{{.ARGOCD_PORT}})..."
+      - cmd: kubectl port-forward -n argocd svc/argocd-server {{.ARGOCD_PORT}}:443 &>/dev/null &
+        platforms: [linux, darwin]
+      - cmd: powershell -Command "Start-Process kubectl -ArgumentList 'port-forward', '-n', 'argocd', 'svc/argocd-server', '{{.ARGOCD_PORT}}:443' -WindowStyle Hidden"
+        platforms: [windows]
+      - cmd: sleep 2
+        platforms: [linux, darwin]
+      - cmd: powershell -Command "Start-Sleep -Seconds 2"
+        platforms: [windows]
+      - echo "Starting kubectl proxy (localhost:{{.KUBECTL_PROXY_PORT}})..."
+      - cmd: kubectl proxy --port={{.KUBECTL_PROXY_PORT}} &>/dev/null &
+        platforms: [linux, darwin]
+      - cmd: powershell -Command "Start-Process kubectl -ArgumentList 'proxy', '--port={{.KUBECTL_PROXY_PORT}}' -WindowStyle Hidden"
+        platforms: [windows]
+      - cmd: sleep 1
+        platforms: [linux, darwin]
+      - cmd: powershell -Command "Start-Sleep -Seconds 1"
+        platforms: [windows]
+
+  dev:portal:start:
+    desc: Generate ArgoCD token and start Backstage
+    internal: true
+    dir: apps/portal
+    cmds:
+      - cmd: |
+          decode_base64() {
+            if printf 'Zg==' | base64 --decode >/dev/null 2>&1; then
+              base64 --decode
+              return
+            fi
+            if printf 'Zg==' | base64 -d >/dev/null 2>&1; then
+              base64 -d
+              return
+            fi
+            if printf 'Zg==' | base64 -D >/dev/null 2>&1; then
+              base64 -D
+              return
+            fi
+            if command -v openssl >/dev/null 2>&1; then
+              openssl base64 -d -A
+              return
+            fi
+            echo "No compatible base64 decoder found" >&2
+            return 1
+          }
+
+          ARGOCD_PASS=$(kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | decode_base64)
+          TOKEN_JSON=$(curl -k -s -X POST \
+            -H "Content-Type: application/json" \
+            -d "{\"username\":\"admin\",\"password\":\"$ARGOCD_PASS\"}" \
+            https://127.0.0.1:{{.ARGOCD_PORT}}/api/v1/session)
+          export ARGOCD_AUTH_TOKEN=$(echo "$TOKEN_JSON" | sed 's/.*"token":"\([^"]*\)".*/\1/')
+          if [ -z "$ARGOCD_AUTH_TOKEN" ] || [ "${#ARGOCD_AUTH_TOKEN}" -lt 20 ]; then
+            echo "WARNING: Could not generate ArgoCD token. ArgoCD features may not work."
+          else
+            echo "ArgoCD token generated."
+          fi
+          yarn start
+        platforms: [linux, darwin]
+      - cmd: powershell -ExecutionPolicy Bypass -File ../../scripts/start-portal.ps1 -ArgocdPort {{.ARGOCD_PORT}}
+        platforms: [windows]
+
+  # ===========================================================================
+  # Testing Tasks
+  # ===========================================================================
+  test:
+    desc: Run all tests
+    cmds:
+      - task: test:operator
+      - task: test:portal
+
+  test:operator:
+    desc: Run operator unit tests
+    dir: apps/operator
+    cmds:
+      - make test
+
+  test:portal:
+    desc: Run portal tests
+    dir: apps/portal
+    cmds:
+      - yarn test
+
+  # ===========================================================================
+  # Teardown Tasks
+  # ===========================================================================
+  clean:
+    desc: Delete the k3d cluster and clean up
+    cmds:
+      - task: clean:cluster
+
+  clean:cluster:
+    desc: Delete the k3d cluster
+    cmds:
+      - k3d cluster delete {{.CLUSTER_NAME}}
+      - echo "Cluster '{{.CLUSTER_NAME}}' deleted."

apps/operator/.devcontainer/devcontainer.json

@@ -1,6 +1,6 @@
 {
   "name": "Kubebuilder DevContainer",
-  "image": "golang:1.24",
+  "image": "golang:1.26",
   "features": {
     "ghcr.io/devcontainers/features/docker-in-docker:2": {},
     "ghcr.io/devcontainers/features/git:1": {}