feat(local-dev): add auto-detection for K3s/Minikube and fix storage …

.dockerignore

@@ -0,0 +1,12 @@
+.git
+.github
+.artifacts
+.idea
+.vscode
+web/node_modules
+web/dist
+docs/node_modules
+docs/public
+node_modules
+tmp
+*.tgz

CONTRIBUTING.md

@@ -190,19 +190,21 @@ Note: While working with the PipeCD codebase, you may refer to [Makefile](./Make
 
 Run `make update/go-deps` and `make update/web-deps` to update the dependencies. Starting a local development environment might fail with errors if the dependencies are not up to date.
 
-#### Starting a local registry
+#### Starting a local registry (Only needed for Kind)
 
-In order to start a local development environment, a registry needs to be running locally.
+If you are using **Kind**, a registry needs to be running locally. Run `make up/local-cluster` to start the cluster and registry.
 
-Run `make up/local-cluster` to start a local registry.
+If you are using **K3s, K3d, or Minikube**, you can skip this step! The build script will automatically detect your cluster type and load the image directly into your local cluster. (To clean up/uninstall later, run `make stop/pipecd`).
 
-This will create the kubernetes namespace `pipecd` if it does not exist and start a local registry in the namespace which can then be accessed by other components.
-
-When cleaning up, run `make down/local-cluster` to stop and delete the registry and the cluster.
+When cleaning up:
+- For **Kind**, run `make down/local-cluster` to stop and delete the registry and the cluster.
+- For **K3s, K3d, or Minikube**, simply run `make stop/pipecd` to uninstall the PipeCD release from your cluster.
 
 #### Run PipeCD Control Plane
 
-Run `make run/pipecd` to run PipeCD Control Plane using your local code changes. This will build and run PipeCD Control Plane.
+Simply run `make run/pipecd` to build and run the PipeCD Control Plane using your local code changes. This will build and deploy the Control Plane on your cluster.
+
+> **Note:** If this is your first time building, `make run/pipecd` will automatically run `make update/web-deps` to install dependencies.
 
 Run `make stop/pipecd` to stop PipeCD Control Plane.
 

Makefile

@@ -160,6 +160,11 @@ run/pipecd: BUILD_LDFLAGS_PREFIX := -X github.com/pipe-cd/pipecd/pkg/version
 run/pipecd: BUILD_OPTS ?= -ldflags "$(BUILD_LDFLAGS_PREFIX).version=$(BUILD_VERSION) $(BUILD_LDFLAGS_PREFIX).gitCommit=$(BUILD_COMMIT) $(BUILD_LDFLAGS_PREFIX).buildDate=$(BUILD_DATE) -w"
 run/pipecd: CONTROL_PLANE_VALUES ?= ./quickstart/control-plane-values.yaml
 run/pipecd:
+	@if [ ! -d "web/node_modules" ]; then \
+		echo "web/node_modules not found. Installing web dependencies first..."; \
+		$(MAKE) update/web-deps; \
+	fi
+
 	@echo "Building go binary of Control Plane..."
 	GOOS=linux GOARCH=amd64 CGO_ENABLED=0 $(BUILD_ENV) go build $(BUILD_OPTS) -o ./.artifacts/pipecd ./cmd/pipecd
 
@@ -168,7 +173,16 @@ run/pipecd:
 
 	@echo "Building docker image and pushing it to local registry..."
 	docker build -f cmd/pipecd/Dockerfile -t localhost:5001/pipecd:$(BUILD_VERSION) .
-	docker push localhost:5001/pipecd:$(BUILD_VERSION)
+	@if kubectl get nodes -o jsonpath='{.items[*].status.nodeInfo.kubeletVersion}' | grep -qi 'k3s\|k3d'; then \
+		echo "Detected K3s/K3d environment. Importing image directly to containerd namespace..."; \
+		docker save localhost:5001/pipecd:$(BUILD_VERSION) | sudo k3s ctr --namespace k8s.io images import -; \
+	elif kubectl config current-context | grep -qi 'minikube' || kubectl get nodes -o wide | grep -qi 'minikube'; then \
+		echo "Detected Minikube environment. Loading image directly..."; \
+		minikube image load localhost:5001/pipecd:$(BUILD_VERSION); \
+	else \
+		echo "Detected Kind/other. Pushing to local registry..."; \
+		docker push localhost:5001/pipecd:$(BUILD_VERSION); \
+	fi
 
 	@echo "Installing Control Plane in kind..."
 	mkdir -p .artifacts
@@ -248,7 +262,7 @@ update/go-deps:
 
 .PHONY: update/web-deps
 update/web-deps:
-	yarn --cwd web install --prefer-offline
+	yarn --cwd web install --prefer-offline --ignore-engines
 
 .PHONY: update/docsy
 update/docsy:

docs/content/en/docs-dev/contribution-guidelines/contributing.md

@@ -56,28 +56,27 @@ make update/web-deps
 
 > Starting a local environment may fail if dependencies are not up to date.
 
-#### 2. Start Local Cluster and Registry
+#### 2. Start Local Cluster and Registry (Kind Only)
 
+If you are using **Kind**, run:
 ```bash
 make up/local-cluster
 ```
 
-This creates the `pipecd` Kubernetes namespace and starts a local registry.
+This creates the `pipecd` Kubernetes namespace and starts a local registry. (To clean up later, run `make down/local-cluster`).
 
-To clean up later:
-
-```bash
-make down/local-cluster
-```
+If you are using **K3s, K3d, or Minikube**, you can skip this step! The build script will automatically detect your cluster type and load the image directly into your local cluster. (To clean up/uninstall later, run `make stop/pipecd`).
 
 #### 3. Run Control Plane
 
+To build and run the PipeCD Control Plane using your local changes:
 ```bash
 make run/pipecd
 ```
 
-To stop:
+> **Note:** If this is your first time building the web frontend, this command will automatically install the web dependencies for you.
 
+To stop:
 ```bash
 make stop/pipecd
 ```

manifests/pipecd/templates/deployment.yaml

@@ -214,6 +214,17 @@ spec:
       {{- if or .Values.serviceAccount.create .Values.serviceAccount.name }}
       serviceAccountName: {{ include "pipecd.serviceAccountName" . }}
       {{- end }}
+      {{- if .Values.localStorageVolumes.enabled }}
+      initContainers:
+        - name: volume-permissions
+          image: alpine:3.20
+          command: ["sh", "-c", "chown -R 999:999 /data"]
+          securityContext:
+            runAsUser: 0
+          volumeMounts:
+            - name: redis-data
+              mountPath: /data
+      {{- end }}
       containers:
         - name: cache
           image: redis:{{ .Values.cache.imageTag }}
@@ -366,6 +377,17 @@ spec:
       {{- if or .Values.serviceAccount.create .Values.serviceAccount.name }}
       serviceAccountName: {{ include "pipecd.serviceAccountName" . }}
       {{- end }}
+      {{- if .Values.localStorageVolumes.enabled }}
+      initContainers:
+        - name: volume-permissions
+          image: alpine:3.20
+          command: ["sh", "-c", "chown -R 999:999 /var/lib/mysql"]
+          securityContext:
+            runAsUser: 0
+          volumeMounts:
+            - name: mysql-data
+              mountPath: /var/lib/mysql
+      {{- end }}
       containers:
         - name: mysql
           image: {{ .Values.mysql.image }}:{{ .Values.mysql.imageTag }}
@@ -420,6 +442,17 @@ spec:
       {{- if or .Values.serviceAccount.create .Values.serviceAccount.name }}
       serviceAccountName: {{ include "pipecd.serviceAccountName" . }}
       {{- end }}
+      {{- if .Values.localStorageVolumes.enabled }}
+      initContainers:
+        - name: volume-permissions
+          image: alpine:3.20
+          command: ["sh", "-c", "chown -R 1000:1000 /data"]
+          securityContext:
+            runAsUser: 0
+          volumeMounts:
+            - name: minio-data
+              mountPath: /data
+      {{- end }}
       containers:
         - name: minio
           image: minio/minio:{{ .Values.minio.imageTag }}