From f0df663c908373b16e6ba0fb8e273f5949e78f16 Mon Sep 17 00:00:00 2001
From: Lukas Wolfsteiner <lukas@wolfsteiner.media>
Date: Sun, 15 Mar 2026 18:25:27 +0000
Subject: [PATCH] [dev/tooling]: add basic devcontainer setup w/ node, pnpm,
 go, nix & recommended tools Add a development container for contributors and
 document how to use it.

- Add .devcontainer/devcontainer.json
- Add .devcontainer/Dockerfile
- Update docs/CONTRIBUTING.md with Dev Container section

- devcontainer.json parses successfully and opens in vscode without issues
- all build.sh variants, recommended tools & lint/typecheck run without issues

Closes #499
---
 .devcontainer/Dockerfile        |  7 ++++++
 .devcontainer/devcontainer.json | 44 +++++++++++++++++++++++++++++++++
 docs/CONTRIBUTING.md            | 17 +++++++++++++
 3 files changed, 68 insertions(+)
 create mode 100644 .devcontainer/Dockerfile
 create mode 100644 .devcontainer/devcontainer.json

diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
new file mode 100644
index 0000000..d838f38
--- /dev/null
+++ b/.devcontainer/Dockerfile
@@ -0,0 +1,7 @@
+FROM mcr.microsoft.com/devcontainers/base:bookworm
+
+ENV DEBIAN_FRONTEND=noninteractive
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends build-essential libnss3-tools mkcert pkg-config && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 0000000..c01d23a
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,44 @@
+{
+  "name": "headplane",
+  "build": {
+    "dockerfile": "Dockerfile"
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "upgradePackages": true,
+      "username": "vscode"
+    },
+    "ghcr.io/devcontainers/features/node:1": {
+      "nodeGypDependencies": true,
+      "version": "22.18"
+    },
+    "ghcr.io/devcontainers/features/go:1": {
+      "version": "1.25.1"
+    },
+    "ghcr.io/devcontainers/features/nix:1": {
+      "extraNixConfig": "experimental-features = nix-command flakes,accept-flake-config = true"
+    }
+  },
+  "containerEnv": {
+    "COREPACK_ENABLE_DOWNLOAD_PROMPT": "0"
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        "golang.go",
+        "ms-azuretools.vscode-docker",
+        "ms-vscode.vscode-typescript-next"
+      ],
+      "settings": {
+        "editor.formatOnSave": true,
+        "go.useLanguageServer": true
+      }
+    }
+  },
+  "forwardPorts": [3000, 5173],
+  "postCreateCommand": "pnpm config set store-dir $HOME/.pnpm-store --global && pnpm install",
+  "remoteUser": "vscode",
+  "updateRemoteUserUID": true
+}
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index d264d88..1a6d747 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -55,3 +55,20 @@ If you plan to work with the WASM SSH agent, you will need to install
 `mkcert` or an equivalent to create certificates in `./test/caddy/certs`.
 It expects a `localhost.pem` and `localhost-key.pem` file to be present in that
 directory. PNPM has a script to do it with `pnpm mkcert` already already.
+
+### Development Container
+
+This repository includes a Dev Container setup in `./.devcontainer` with:
+
+- Node.js
+- PNPM
+- Go
+- Nix
+- `mkcert` and related local certificate tooling
+
+Open the repository in VS Code (or any Dev Container compatible editor) and
+start the container. On first creation, dependencies are installed automatically
+with `pnpm install`.
+
+The base image is Debian (instead of Alpine) to keep compatibility with common
+official Dev Container features used by this project (Node, Go, and Docker).