CONTRIBUTING.md

Contributing Guidelines

Welcome to Kubernetes. We are excited about the prospect of you joining our community! The Kubernetes community abides by the CNCF code of conduct. Here is an excerpt:

As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.

Getting Started

For contributing to the Headlamp project, please refer check out our:

• Guidelines
• Code of Conduct,
• #headlamp slack channel in the Kubernetes Slack
• Monthly Community Meeting

Since Headlamp is part of the Kubernetes Community, please read also:

• Contributor License Agreement Kubernetes projects require that you sign a Contributor License Agreement (CLA) before we can accept your pull requests
• Kubernetes Contributor Guide - Main contributor documentation, or you can just jump directly to the contributing section
• Contributor Cheat Sheet - Common resources for existing developers

Local Development Setup

Ready to run Headlamp locally? Here's the full setup from scratch.

Prerequisites

Make sure you have Node.js (>= 20.11.1 with npm >= 10.0.0) and Go installed before starting; see the development dependencies for the full list.

Build and Run

1. Install root dependencies

   npm install

2. Build the backend (requires Go)

   npm run backend:build

3. Install frontend dependencies

   cd frontend
   npm install
   cd ..

4. Start the application

   npm start

That's it—you should now have Headlamp running locally.

Apple Silicon (ARM64)

If you're developing on an M1/M2/M3 Mac and want to use Minikube, you'll need a driver that supports ARM64. Two good options:

• docker – uses the Docker runtime
• vfkit – a lightweight hypervisor for macOS

Example commands:

minikube start --driver=docker

or

minikube start --driver=vfkit

Note: VirtualBox does not support ARM64. Avoid --driver=virtualbox on Apple Silicon.

macOS Gatekeeper / Security Warning

When you first launch the Headlamp app on macOS, you might see a warning that the app is "damaged" or can't be opened. This is due to Gatekeeper's quarantine flag.

Run the following command using the actual path to your .app file:

xattr -cr /path/to/Headlamp.app

Then try opening the app again.