Improve headlamp port clashes #4121

joaquimrocha · 2025-11-03T18:57:17Z

Summary

This PR improves the UX when there's already a service using the default port that Headlamp's backend uses.

It also stops showing the dialog when there's already a running headlamp-server process, unless it ran out of ports to try.

Related Issue

Fixes #3447

Steps to Test

Regular conflict:

Run headlamp-server (will use port 4466 by default)
Run the Healdamp app -> should still run fine. Check the output of the electron process (or the dev tools' network requests) to see that the backend was started using port 4467

No ports available because headlamp-server is occupying them:

Run headlamp-server (will use port 4466 by default)
export HEADLAMP_MAX_PORT_ATTEMPTS=1 and run the Healdamp app -> Should show a dialog saying that there are no ports free and offering the user the possibility to terminate the other processes or quit the app

No ports available because another process is occupying them:

Run python3 -m http.server 4466
export HEADLAMP_MAX_PORT_ATTEMPTS=1 and run the Healdamp app -> Should show a dialog saying that there are no ports free but not offer the possibility to kill those processes.

Testing done

k8s-ci-robot · 2025-11-03T18:57:26Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: joaquimrocha

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [joaquimrocha]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

joaquimrocha · 2025-11-04T13:21:46Z

Nevermind those commits I added before. That was a branch name confusion. I have added the right commits back.

sniok · 2025-11-04T15:01:55Z

app/electron/main.ts

+      if (err.code === 'EADDRINUSE') {
+        resolve(false);
+      } else {
+        resolve(false);


seems like this if is not needed

skoeva · 2025-11-04T21:52:14Z

rebased against main

skoeva

looks like headlamp app runs now with the backend server running in another terminal, but the output for the app start command still shows localhost:4466 as the listen address.

maybe the testing steps could be updated too because I got inconsistent output across different start commands (npm run star sometimes showed 4467 but npm run start consistently shows 4466)

joaquimrocha · 2025-11-05T11:21:52Z

looks like headlamp app runs now with the backend server running in another terminal, but the output for the app start command still shows localhost:4466 as the listen address.

Can you share how you tested?

maybe the testing steps could be updated too because I got inconsistent output across different start commands (npm run star sometimes showed 4467 but npm run start consistently shows 4466)

Are you sure you do not have any instance running when you start the commands?

Copilot

Pull Request Overview

This PR implements dynamic backend port configuration for Headlamp's Electron app to support multiple running instances. It introduces automatic port discovery (trying ports 4466-4565 by default), allows the frontend to dynamically connect to the backend's actual port, and adds user dialogs to handle port conflicts with existing Headlamp processes.

Adds automatic port selection with fallback when default port 4466 is occupied
Refactors frontend URL generation to use runtime port configuration via window.headlampBackendPort
Implements port conflict detection and resolution with user prompts
Adds internationalization strings for new port-related error dialogs

Reviewed Changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
frontend/vite.config.ts	Adds HEADLAMP_PORT environment variable support for configurable backend port in Vite dev proxy
frontend/src/lib/k8s/api/v2/webSocket.ts	Replaces static BASE_WS_URL with getBaseWsUrl() function for runtime port resolution
frontend/src/lib/k8s/api/v2/fetch.ts	Updates backendFetch to use getAppUrl() directly instead of static BASE_HTTP_URL
frontend/src/lib/k8s/api/v1/streamingApi.ts	Replaces static BASE_WS_URL with getBaseWsUrl() function for WebSocket connections
frontend/src/lib/k8s/api/v1/constants.ts	Adds deprecation warning for BASE_HTTP_URL constant
frontend/src/lib/k8s/api/v1/clusterRequests.ts	Updates clusterRequest to use getAppUrl() directly instead of static constant
frontend/src/i18n/locales/*/app.json	Adds translation placeholders for port conflict error messages
frontend/src/helpers/getAppUrl.ts	Implements window.headlampBackendPort support and refactors port selection logic
app/scripts/start.js	Passes environment variables to frontend process (minor change)
app/electron/preload.ts	Adds IPC channels for backend port communication
app/electron/main.ts	Implements port discovery, conflict detection, and injects actualPort into window object

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

frontend/vite.config.ts

frontend/src/lib/k8s/api/v2/webSocket.ts

frontend/src/lib/k8s/api/v1/streamingApi.ts

frontend/src/helpers/getAppUrl.ts

Copilot · 2025-11-05T11:49:58Z

app/electron/main.ts

+      if (err.code === 'EADDRINUSE') {
+        resolve(false);
+      } else {
+        resolve(false);
+      }


The if-else branches have identical logic (both resolve(false)). This can be simplified to just resolve(false) without the conditional check.

Suggested change

if (err.code === 'EADDRINUSE') {

resolve(false);

} else {

resolve(false);

}

resolve(false);

This looks like a bug. Not sure about the solution suggested.

Copilot · 2025-11-05T11:49:58Z

app/electron/main.ts

      }
+
+      // Inject the backend port into the window object
+      mainWindow?.webContents.executeJavaScript(`window.headlampBackendPort = ${actualPort};`);


Direct string interpolation in executeJavaScript can be vulnerable to injection if actualPort is not properly validated. Although actualPort is a number in this context, it's better to use JSON.stringify or validate that actualPort is indeed a number before injection.

Suggested change

mainWindow?.webContents.executeJavaScript(`window.headlampBackendPort = ${actualPort};`);

mainWindow?.webContents.executeJavaScript(`window.headlampBackendPort = ${JSON.stringify(actualPort)};`);

Copilot · 2025-11-05T11:49:58Z

app/electron/main.ts

+
+      // Update the environment variable for the frontend
+      if (mainWindow) {
+        mainWindow.webContents.executeJavaScript(`window.headlampBackendPort = ${actualPort};`);


Direct string interpolation in executeJavaScript can be vulnerable to injection if actualPort is not properly validated. Although actualPort is a number in this context, it's better to use JSON.stringify or validate that actualPort is indeed a number before injection.

Suggested change

mainWindow.webContents.executeJavaScript(`window.headlampBackendPort = ${actualPort};`);

mainWindow.webContents.executeJavaScript(`window.headlampBackendPort = ${JSON.stringify(actualPort)};`);

illume · 2025-11-05T12:15:01Z

app/electron/main.ts

+    );
+    return headlampOnPort.map(p => p.pid);
+  } catch (error) {
+    console.error(`Error checking if port ${port} is used by Headlamp:`, error);


Remove "Headlamp"? Because it might be called something else.

(and in other parts of this PR/file too)

illume · 2025-11-05T12:21:41Z

I closed the copilot notes which were wrong.

Reviewed it, except for the main.ts electron stuff in detail.

I added a bit of a testing checklist for things I think could be broken.
(Mostly we need to make sure we test each platform. The npm star is important because windows dev mode is basically broken with npm start. We cover container testing in CI, but not compiled apps.)

k8s-ci-robot requested review from illume and skoeva November 3, 2025 18:57

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Nov 3, 2025

joaquimrocha force-pushed the improve-headlamp-port-clashes branch from b28437e to ea98bad Compare November 3, 2025 18:57

k8s-ci-robot added approved Indicates a PR has been approved by an approver from all required OWNERS files. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Nov 3, 2025

joaquimrocha force-pushed the improve-headlamp-port-clashes branch 2 times, most recently from b921cb2 to 2b17d29 Compare November 4, 2025 13:10

k8s-ci-robot added needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. and removed size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Nov 4, 2025

joaquimrocha force-pushed the improve-headlamp-port-clashes branch 2 times, most recently from 1e11684 to 574e504 Compare November 4, 2025 13:16

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 4, 2025

joaquimrocha force-pushed the improve-headlamp-port-clashes branch from 574e504 to b921cb2 Compare November 4, 2025 13:20

k8s-ci-robot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. and removed size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Nov 4, 2025

joaquimrocha added this to Headlamp Release Plan / Roadmap Nov 4, 2025

joaquimrocha added this to the v0.38.0 milestone Nov 4, 2025

github-project-automation bot moved this to Queued in Headlamp Release Plan / Roadmap Nov 4, 2025

joaquimrocha moved this from Queued to In Progress in Headlamp Release Plan / Roadmap Nov 4, 2025

sniok reviewed Nov 4, 2025

View reviewed changes

joaquimrocha added 2 commits November 4, 2025 16:51

app,frontend: Allow to start with a different port

acbb55e

app: Try different ports if the default one is occupied

f35248e

skoeva force-pushed the improve-headlamp-port-clashes branch from b921cb2 to f35248e Compare November 4, 2025 21:51

skoeva reviewed Nov 4, 2025

View reviewed changes

illume requested a review from Copilot November 5, 2025 11:46

Copilot AI reviewed Nov 5, 2025

View reviewed changes

illume reviewed Nov 5, 2025

View reviewed changes

	mainWindow?.webContents.executeJavaScript(`window.headlampBackendPort = ${actualPort};`);
	mainWindow?.webContents.executeJavaScript(`window.headlampBackendPort = ${JSON.stringify(actualPort)};`);

	mainWindow.webContents.executeJavaScript(`window.headlampBackendPort = ${actualPort};`);
	mainWindow.webContents.executeJavaScript(`window.headlampBackendPort = ${JSON.stringify(actualPort)};`);

Improve headlamp port clashes #4121

Are you sure you want to change the base?

Improve headlamp port clashes #4121

Conversation

joaquimrocha commented Nov 3, 2025 • edited by illume Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Steps to Test

Testing done

Uh oh!

k8s-ci-robot commented Nov 3, 2025

Uh oh!

joaquimrocha commented Nov 4, 2025

Uh oh!

sniok Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

skoeva commented Nov 4, 2025

Uh oh!

skoeva left a comment

Choose a reason for hiding this comment

Uh oh!

joaquimrocha commented Nov 5, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

illume Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

illume Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

illume commented Nov 5, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

joaquimrocha commented Nov 3, 2025 •

edited by illume

Loading

illume Nov 5, 2025 •

edited

Loading