chore: enhance devcontainer setup for local k3s development and updated contribution guidelines

.agents/skills/grill-me/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: grill-me
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.

.devcontainer/devcontainer.env_template

@@ -0,0 +1,3 @@
+NEXTAUTH_SECRET=ADD_A_STRONG_SECRET
+DATABASE_URL="file:/workspace/storage/db/data.db"
+USE_LOCAL_DOCKER_K3S=true

.devcontainer/devcontainer.json

@@ -1,6 +1,6 @@
 {
-	"name": "quick-stack",
-	"dockerComposeFile": "./docker.compose.yml",
+	"name": "QuickStack",
+	"dockerComposeFile": "docker.compose.yml",
 	"service": "vscode-container",
 	"workspaceFolder": "/workspace",
 	"shutdownAction": "stopCompose",
@@ -14,18 +14,16 @@
 				"bradlc.vscode-tailwindcss",
 				"GitHub.copilot",
 				"GitHub.copilot-chat",
-				"oven.bun-vscode",
 				"christian-kohler.path-intellisense",
 				"esbenp.prettier-vscode",
 				"VisualStudioExptTeam.vscodeintellicode",
 				"mhutchie.git-graph",
 				"donjayamanne.githistory",
 				"qwtel.sqlite-viewer",
-				"mindaro.mindaro",
-				"shd101wyy.markdown-preview-enhanced",
 				"ms-kubernetes-tools.vscode-kubernetes-tools"
 			]
 		}
 	},
-	"postCreateCommand": "curl -fsSL https://bun.sh/install | bash"
+	"postStartCommand": "bash .devcontainer/start-k3s.sh",
+	"remoteUser": "node"
 }

.devcontainer/docker.compose.yml

@@ -1,11 +1,31 @@
 version: "3"
 services:
   vscode-container:
-    image: mcr.microsoft.com/devcontainers/typescript-node
-    #image: mcr.microsoft.com/devcontainers/base:debian
-    #image: mcr.microsoft.com/devcontainers/base:alpine
+    image: mcr.microsoft.com/devcontainers/typescript-node:22
     command: /bin/sh -c "while sleep 1000; do :; done"
     volumes:
       - ..:/workspace
       - ~/.ssh:/home/node/.ssh
-    env_file: devcontainer.env
+      - qs-k3s-dev-kubeconfig:/k3s-config:ro
+    env_file: devcontainer.env
+    depends_on:
+      - qs-k3s-dev
+
+  qs-k3s-dev:
+    image: rancher/k3s:v1.31.3-k3s1
+    privileged: true
+    hostname: qs-k3s-dev
+    cgroup: host
+    command: ["server", "--snapshotter=native", "--write-kubeconfig-mode=644", "--tls-san=k3s"]
+    tmpfs:
+      - /run
+      - /var/run
+    ports:
+      - "6443:6443"
+    volumes:
+      - qs-k3s-dev-kubeconfig:/etc/rancher/k3s
+      - qs-k3s-dev-data:/var/lib/rancher/k3s
+
+volumes:
+  qs-k3s-dev-kubeconfig:
+  qs-k3s-dev-data:

.devcontainer/start-k3s.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -e
+
+KUBECONFIG_SOURCE="/k3s-config/k3s.yaml"
+KUBECONFIG_DEST="kube-config.config"
+
+if [[ "$USE_LOCAL_DOCKER_K3S" == "true" ]]; then
+    echo "Waiting for k3s kubeconfig to be created"
+    until [ -f "$KUBECONFIG_SOURCE" ]; do
+        sleep 2
+        printf "."
+    done
+    echo ""
+
+    echo "k3s kubeconfig found. Writing $KUBECONFIG_DEST..."
+    # Replace 127.0.0.1 with the qs-k3s-dev service name and skip TLS verification
+    sed \
+        -e 's/127\.0\.0\.1/qs-k3s-dev/g' \
+        -e 's/certificate-authority-data:.*/insecure-skip-tls-verify: true/' \
+        "$KUBECONFIG_SOURCE" > "$KUBECONFIG_DEST"
+
+    echo "k3s kubeconfig is ready at $KUBECONFIG_DEST"
+else
+    echo "USE_LOCAL_DOCKER_K3S is not set to 'true', skipping k3s kubeconfig setup."
+    echo "Using existing $KUBECONFIG_DEST if present."
+fi
+
+echo ""
+echo ""
+echo "***************************************"
+echo " > Development environment is ready! < "
+echo "***************************************"
+echo ""
+echo ""

CONTRIBUTING.md

@@ -76,10 +76,57 @@ yarn test
 
 ### Environment Setup
 
-To setup a developement environment, use the provided devcontainer configuration. This will setup a development environment with all necessary dependencies and the correct node version.
+To set up a development environment, use the provided devcontainer configuration. This will set up a development environment with all necessary dependencies and the correct Node version.
+
+In order to run QuickStack, a kubernetes (k3s) cluster is required. There are two ways to connect the devcontainer to a Kubernetes cluster:
+
+#### Option 1: Local Docker k3s (simple, limited)
+
+The devcontainer includes a lightweight k3s cluster running as a Docker container. This is the easiest way to get started and is sufficient for most development and unit testing.
+
+**Limitations:** This local cluster does not include Longhorn (persistent storage) or cert-manager (HTTPS). As a result, you cannot fully test features that rely on volumes or browse deployed apps via HTTPS.
+
+To use this option:
+1. Copy `.devcontainer/devcontainer.env_template` to `.devcontainer/devcontainer.env`.
+2. Make sure `USE_LOCAL_DOCKER_K3S=true` is set in `devcontainer.env`.
+3. Open the project in the devcontainer — the kubeconfig will be configured automatically.
+
+#### Option 2: External VM / VPS with full QuickStack setup (recommended for full testing)
+
+To test all QuickStack features (Longhorn volumes, HTTPS, deployed app access), a VM or VPS with a full QuickStack installation is required.
+
+1. Install QuickStack on the VPS/VM by running the following command:
+   ```sh
+   curl -sfL https://get.quickstack.dev/setup.sh | sh -
+   ```
+2. Copy the kubeconfig from the VM (`/etc/rancher/k3s/k3s.yaml`) to `kube-config.config` in the root of the project.
+3. add insecure-skip-tls-verify: true to the cluster configuration in `kube-config.config` (see example below).
+4. Copy `.devcontainer/devcontainer.env_template` to `.devcontainer/devcontainer.env` and set `USE_LOCAL_DOCKER_K3S=false`.
+
+Example `kube-config.config`:
+```yaml
+apiVersion: v1
+clusters:
+- cluster:
+    insecure-skip-tls-verify: true
+    server: https://SOME-IP-ADDRESS-OR-HOSTNAME:6443
+  name: default
+contexts:
+- context:
+    cluster: default
+    namespace: registry-and-build
+    user: default
+  name: default
+current-context: default
+kind: Config
+users:
+- name: default
+  user:
+    client-certificate-data: .....
+    client-key-data: .....
+```
 
-Additionally to the devcontainer, you need a running k3s cluster.
-To connect to your own k3s test cluster, provide the kuberentes credentials in the file `k3s-config.yaml` in the root of the project.
+If you run into any issues, feel free to reach out and open an issue.
 
 #### Install Dependencies
 ```sh

skills-lock.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "skills": {
+    "grill-me": {
+      "source": "mattpocock/skills",
+      "sourceType": "github",
+      "computedHash": "784f0dbb7403b0f00324bce9a112f715342777a0daee7bbb7385f9c6f0a170ea"
+    }
+  }
+}