From 3122de618d51d134cb9d6197eff0887e4a7a6912 Mon Sep 17 00:00:00 2001 From: biersoeckli Date: Fri, 3 Apr 2026 10:29:09 +0000 Subject: [PATCH] chore: enhance devcontainer setup for local k3s development and update contribution guidelines --- .agents/skills/grill-me/SKILL.md | 10 +++++ .devcontainer/devcontainer.env_example | 2 - .devcontainer/devcontainer.env_template | 3 ++ .devcontainer/devcontainer.json | 10 ++--- .devcontainer/docker.compose.yml | 28 +++++++++++-- .devcontainer/start-k3s.sh | 34 ++++++++++++++++ CONTRIBUTING.md | 53 +++++++++++++++++++++++-- skills-lock.json | 10 +++++ 8 files changed, 135 insertions(+), 15 deletions(-) create mode 100644 .agents/skills/grill-me/SKILL.md delete mode 100644 .devcontainer/devcontainer.env_example create mode 100644 .devcontainer/devcontainer.env_template create mode 100644 .devcontainer/start-k3s.sh create mode 100644 skills-lock.json diff --git a/.agents/skills/grill-me/SKILL.md b/.agents/skills/grill-me/SKILL.md new file mode 100644 index 0000000..bd04394 --- /dev/null +++ b/.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. diff --git a/.devcontainer/devcontainer.env_example b/.devcontainer/devcontainer.env_example deleted file mode 100644 index f3c3f26..0000000 --- a/.devcontainer/devcontainer.env_example +++ /dev/null @@ -1,2 +0,0 @@ -NEXTAUTH_SECRET=SOME_TOKEN_FOR_NEXTJS_AUTHENTICATION -DATABASE_URL="file:/workspace/storage/db/data.db" \ No newline at end of file diff --git a/.devcontainer/devcontainer.env_template b/.devcontainer/devcontainer.env_template new file mode 100644 index 0000000..499c8f7 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index be84d03..649f12d 100644 --- a/.devcontainer/devcontainer.json +++ b/.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" } \ No newline at end of file diff --git a/.devcontainer/docker.compose.yml b/.devcontainer/docker.compose.yml index e693da7..1a8dc01 100644 --- a/.devcontainer/docker.compose.yml +++ b/.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 \ No newline at end of file + - 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: diff --git a/.devcontainer/start-k3s.sh b/.devcontainer/start-k3s.sh new file mode 100644 index 0000000..14d2f96 --- /dev/null +++ b/.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 "" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0f13f2f..cce6c13 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/skills-lock.json b/skills-lock.json new file mode 100644 index 0000000..b1c9c77 --- /dev/null +++ b/skills-lock.json @@ -0,0 +1,10 @@ +{ + "version": 1, + "skills": { + "grill-me": { + "source": "mattpocock/skills", + "sourceType": "github", + "computedHash": "784f0dbb7403b0f00324bce9a112f715342777a0daee7bbb7385f9c6f0a170ea" + } + } +}