Skip to content

Commit e25856c

Browse files
biersoecklibiersoeckli
authored
Merge pull request #81 from biersoeckli/feat/update-devcontainer-for-easy-dev-setup
chore: enhance devcontainer setup for local k3s development and updated contribution guidelines
2 parents 74becb9 + 3122de6 commit e25856c

8 files changed

Lines changed: 135 additions & 15 deletions

File tree

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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
name: grill-me
3+
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".
4+
---
5+
6+
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.
7+
8+
Ask the questions one at a time.
9+
10+
If a question can be answered by exploring the codebase, explore the codebase instead.

‎.devcontainer/devcontainer.env_example‎

Lines changed: 0 additions & 2 deletions
This file was deleted.

‎.devcontainer/devcontainer.env_template‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
NEXTAUTH_SECRET=ADD_A_STRONG_SECRET
2+
DATABASE_URL="file:/workspace/storage/db/data.db"
3+
USE_LOCAL_DOCKER_K3S=true

‎.devcontainer/devcontainer.json‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
2-
"name": "quick-stack",
3-
"dockerComposeFile": "./docker.compose.yml",
2+
"name": "QuickStack",
3+
"dockerComposeFile": "docker.compose.yml",
44
"service": "vscode-container",
55
"workspaceFolder": "/workspace",
66
"shutdownAction": "stopCompose",
@@ -14,18 +14,16 @@
1414
"bradlc.vscode-tailwindcss",
1515
"GitHub.copilot",
1616
"GitHub.copilot-chat",
17-
"oven.bun-vscode",
1817
"christian-kohler.path-intellisense",
1918
"esbenp.prettier-vscode",
2019
"VisualStudioExptTeam.vscodeintellicode",
2120
"mhutchie.git-graph",
2221
"donjayamanne.githistory",
2322
"qwtel.sqlite-viewer",
24-
"mindaro.mindaro",
25-
"shd101wyy.markdown-preview-enhanced",
2623
"ms-kubernetes-tools.vscode-kubernetes-tools"
2724
]
2825
}
2926
},
30-
"postCreateCommand": "curl -fsSL https://bun.sh/install | bash"
27+
"postStartCommand": "bash .devcontainer/start-k3s.sh",
28+
"remoteUser": "node"
3129
}

‎.devcontainer/docker.compose.yml‎

Lines changed: 24 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,31 @@
11
version: "3"
22
services:
33
vscode-container:
4-
image: mcr.microsoft.com/devcontainers/typescript-node
5-
#image: mcr.microsoft.com/devcontainers/base:debian
6-
#image: mcr.microsoft.com/devcontainers/base:alpine
4+
image: mcr.microsoft.com/devcontainers/typescript-node:22
75
command: /bin/sh -c "while sleep 1000; do :; done"
86
volumes:
97
- ..:/workspace
108
- ~/.ssh:/home/node/.ssh
11-
env_file: devcontainer.env
9+
- qs-k3s-dev-kubeconfig:/k3s-config:ro
10+
env_file: devcontainer.env
11+
depends_on:
12+
- qs-k3s-dev
13+
14+
qs-k3s-dev:
15+
image: rancher/k3s:v1.31.3-k3s1
16+
privileged: true
17+
hostname: qs-k3s-dev
18+
cgroup: host
19+
command: ["server", "--snapshotter=native", "--write-kubeconfig-mode=644", "--tls-san=k3s"]
20+
tmpfs:
21+
- /run
22+
- /var/run
23+
ports:
24+
- "6443:6443"
25+
volumes:
26+
- qs-k3s-dev-kubeconfig:/etc/rancher/k3s
27+
- qs-k3s-dev-data:/var/lib/rancher/k3s
28+
29+
volumes:
30+
qs-k3s-dev-kubeconfig:
31+
qs-k3s-dev-data:

‎.devcontainer/start-k3s.sh‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
#!/usr/bin/env bash
2+
set -e
3+
4+
KUBECONFIG_SOURCE="/k3s-config/k3s.yaml"
5+
KUBECONFIG_DEST="kube-config.config"
6+
7+
if [[ "$USE_LOCAL_DOCKER_K3S" == "true" ]]; then
8+
echo "Waiting for k3s kubeconfig to be created"
9+
until [ -f "$KUBECONFIG_SOURCE" ]; do
10+
sleep 2
11+
printf "."
12+
done
13+
echo ""
14+
15+
echo "k3s kubeconfig found. Writing $KUBECONFIG_DEST..."
16+
# Replace 127.0.0.1 with the qs-k3s-dev service name and skip TLS verification
17+
sed \
18+
-e 's/127\.0\.0\.1/qs-k3s-dev/g' \
19+
-e 's/certificate-authority-data:.*/insecure-skip-tls-verify: true/' \
20+
"$KUBECONFIG_SOURCE" > "$KUBECONFIG_DEST"
21+
22+
echo "k3s kubeconfig is ready at $KUBECONFIG_DEST"
23+
else
24+
echo "USE_LOCAL_DOCKER_K3S is not set to 'true', skipping k3s kubeconfig setup."
25+
echo "Using existing $KUBECONFIG_DEST if present."
26+
fi
27+
28+
echo ""
29+
echo ""
30+
echo "***************************************"
31+
echo " > Development environment is ready! < "
32+
echo "***************************************"
33+
echo ""
34+
echo ""

‎CONTRIBUTING.md‎

Lines changed: 50 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -76,10 +76,57 @@ yarn test
7676

7777
### Environment Setup
7878

79-
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.
79+
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.
80+
81+
In order to run QuickStack, a kubernetes (k3s) cluster is required. There are two ways to connect the devcontainer to a Kubernetes cluster:
82+
83+
#### Option 1: Local Docker k3s (simple, limited)
84+
85+
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.
86+
87+
**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.
88+
89+
To use this option:
90+
1. Copy `.devcontainer/devcontainer.env_template` to `.devcontainer/devcontainer.env`.
91+
2. Make sure `USE_LOCAL_DOCKER_K3S=true` is set in `devcontainer.env`.
92+
3. Open the project in the devcontainer — the kubeconfig will be configured automatically.
93+
94+
#### Option 2: External VM / VPS with full QuickStack setup (recommended for full testing)
95+
96+
To test all QuickStack features (Longhorn volumes, HTTPS, deployed app access), a VM or VPS with a full QuickStack installation is required.
97+
98+
1. Install QuickStack on the VPS/VM by running the following command:
99+
```sh
100+
curl -sfL https://get.quickstack.dev/setup.sh | sh -
101+
```
102+
2. Copy the kubeconfig from the VM (`/etc/rancher/k3s/k3s.yaml`) to `kube-config.config` in the root of the project.
103+
3. add insecure-skip-tls-verify: true to the cluster configuration in `kube-config.config` (see example below).
104+
4. Copy `.devcontainer/devcontainer.env_template` to `.devcontainer/devcontainer.env` and set `USE_LOCAL_DOCKER_K3S=false`.
105+
106+
Example `kube-config.config`:
107+
```yaml
108+
apiVersion: v1
109+
clusters:
110+
- cluster:
111+
insecure-skip-tls-verify: true
112+
server: https://SOME-IP-ADDRESS-OR-HOSTNAME:6443
113+
name: default
114+
contexts:
115+
- context:
116+
cluster: default
117+
namespace: registry-and-build
118+
user: default
119+
name: default
120+
current-context: default
121+
kind: Config
122+
users:
123+
- name: default
124+
user:
125+
client-certificate-data: .....
126+
client-key-data: .....
127+
```
80128
81-
Additionally to the devcontainer, you need a running k3s cluster.
82-
To connect to your own k3s test cluster, provide the kuberentes credentials in the file `k3s-config.yaml` in the root of the project.
129+
If you run into any issues, feel free to reach out and open an issue.
83130
84131
#### Install Dependencies
85132
```sh

‎skills-lock.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"version": 1,
3+
"skills": {
4+
"grill-me": {
5+
"source": "mattpocock/skills",
6+
"sourceType": "github",
7+
"computedHash": "784f0dbb7403b0f00324bce9a112f715342777a0daee7bbb7385f9c6f0a170ea"
8+
}
9+
}
10+
}

0 commit comments

Comments
 (0)