rancher-sandbox/rancher-desktop

Container Management and Kubernetes on the Desktop

Rancher Desktop

Rancher Desktop is an open-source project that brings Kubernetes and container management to the desktop. It runs on Windows, macOS and Linux. This README pertains to the development of Rancher Desktop. For user-oriented information about Rancher Desktop, please see rancherdesktop.io. For user-oriented documentation, please see docs.rancherdesktop.io.

Overview

Rancher Desktop is an Electron application that is mainly written in TypeScript. It bundles a variety of other technologies in order to provide one cohesive application. It includes a command line tool, rdctl, which is written in Go. Most developer activities, such as running a development build, building/packaging Rancher Desktop, running unit tests, and running end-to-end tests, are done through yarn scripts. Some exceptions exist, such as running BATS tests.

Setup

Windows

There are two options for building from source on Windows: with a Development VM Setup or Manual Development Environment Setup with an existing Windows installation.

Development VM Setup

1. Download a Microsoft Windows 10 development virtual machine. All of the following steps should be done in that virtual machine.

2. Open a PowerShell prompt (hit Windows Key + X and open Windows PowerShell).

3. Run the automated setup script:

   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
   iwr -useb 'https://github.com/rancher-sandbox/rancher-desktop/raw/main/scripts/windows-setup.ps1' | iex

4. Close the privileged PowerShell prompt.

5. Ensure msbuild_path and msvs_version are configured correctly in .npmrc file. Run the following commands to set these properties:

   npm config set msvs_version <visual-studio-version-number>
   npm config set msbuild_path <path/to/MSBuild.exe>
   

   For example for Visual Studio 2022:

   npm config set msvs_version 2022
   npm config set msbuild_path "C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe"
   

   If you get an error message when trying to run npm config set..., run npm config edit and then add lines like

   msvs_version=2022
   msbuild_path=C:\Program Files (x86)\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe
   

   Do not quote the values to the right side of the equal sign. The quotes aren't needed, and it's possible that some processors will treat them as literal parts of the path, and then fail.

6. Configure git to work with linux- and macos-originated files:

   git config --global --replace-all core.autocrlf false
   git config --global --replace-all core.eol lf
   

If you find the lint:go tests are failing mysteriously, it's possible that the line-endings are incorrect.

You can now clone the repository and run yarn.

Manual Development Environment Setup

1. Install Windows Subsystem for Linux (WSL) on your machine. Skip this step, if WSL is already installed.
2. Open a PowerShell prompt (hit Windows Key + X and open Windows PowerShell).
3. Install Scoop via iwr -useb get.scoop.sh | iex.
4. Install 7zip, git, go, mingw, nvm, and unzip via scoop install 7zip git go mingw nvm python unzip. Check node version with nvm list. If node v18 is not installed or set as the current version, then install using nvm install 18 and set as current using nvm use 18.xx.xx.
5. Install the yarn package manager via npm install --global yarn
6. Install Visual Studio 2017 or higher. As of this writing the latest version is available at [https://visualstudio.microsoft.com/downloads/]; if that's changed, a good search engine should find it.
7. Make sure you have the Windows SDK component installed. This Visual Studio docs describes steps to install components. The Desktop development with C++ workload needs to be selected, too.
8. Configure git to work with linux- and macos-originated files:

   git config --global --replace-all core.autocrlf false
   git config --global --replace-all core.eol lf
   

If you find the lint:go tests are failing mysteriously, it's possible that the line-endings are incorrect. 9. Ensure msbuild_path and msvs_version are configured correctly in .npmrc file. Run the following commands to set these properties:

npm config set msvs_version <visual-studio-version-number>
npm config set msbuild_path <path/to/MSBuild.exe>

For example for Visual Studio 2022:

npm config set msvs_version 2022
npm config set msbuild_path "C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe"

If you get an error message when trying to run npm config set..., run npm config edit and then add lines like

msvs_version=2022
msbuild_path=C:\Program Files (x86)\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe

Do not quote the values to the right side of the equal sign. They aren't needed, and it's possible that some processor will treat them as literal parts of the path, and then fail.

You can now clone the repository and run yarn.

macOS

Install nvm to get Node.js and npm:

See https://github.com/nvm-sh/nvm#installing-and-updating and run the curl or wget command to install nvm.

Note that this script adds code dealing with nvm to a profile file (like ~/.bash_profile). To add access to nvm to a current shell session, you'll need to source that file.

Currently we build Rancher Desktop with Node 18. To install it, run:

nvm install 18.16

Next, you'll need to install the yarn package manager:

npm install --global yarn

You'll also need to run brew install go if you haven't installed go.

Then you can install dependencies with:

yarn

⚠️ Working on a mac with an M1 chip?

You will need to set the M1 environment variable before installing dependencies and running any npm scripts:

export M1=1
yarn

You will want to run git clean -fdx to clean out any cached assets and re-downloaded with the correct arch before running yarn if you previously installed dependencies without setting M1 first.

Linux

Ensure you have the following installed:

• Node.js v18. Make sure you have any development packages installed. For example, on openSUSE Leap 15.3 you would need to install nodejs18 and nodejs18-devel.

• yarn classic

• Go 1.21 or later.

• Dependencies described in the node-gyp docs installation. This is required to install the ffi-napi npm package. These docs mention "a proper C/C++ compiler toolchain". You can install gcc and g++ for this.

Then you can install dependencies with:

yarn

You can then run Rancher Desktop as described below. It may fail on the first run - if this happens, try doing a factory reset and re-running, which has been known to solve this issue.

Running

Once you have your dependencies installed you can run a development version of Rancher Desktop with:

yarn dev

Tests

To run the unit tests:

yarn test

To run the integration tests:

yarn test:e2e

Building

Rancher can be built from source on Windows, macOS or Linux. Cross-compilation is currently not supported. To run a build do:

yarn build
yarn package

The build output goes to dist/.

Debugging builds with the Chrome remote debugger

The Chrome remote debugger allows you to debug Electron apps using Chrome Developer Tools. You can use it to access log messages that might output to the developer console of the renderer process. This is especially helpful for getting additional debug information in production builds of Rancher Desktop.

Starting Rancher Desktop with Remote Debugging Enabled

To enable remote debugging, start Rancher Desktop with the --remote-debugging-port argument.

On Linux, start Rancher Desktop with the following command:

rancher-desktop --remote-debugging-port="8315" --remote-allow-origins=http://localhost:8315

On macOS, start Rancher Desktop with the following command:

/Applications/Rancher\ Desktop.app/Contents/MacOS/Rancher\ Desktop --remote-debugging-port="8315" --remote-allow-origins=http://localhost:8315

On Windows, start Rancher Desktop with the following command:

cd 'C:\Program Files\Rancher Desktop\'
& '.\Rancher Desktop.exe' --remote-debugging-port="8315" --remote-allow-origins=http://localhost:8315

After Rancher Desktop starts, open Chrome and navigate to http://localhost:8315/. Select the available target to start remote debugging Rancher Desktop.

Remote Debugging an Extension

To remote debug an extension, follow the same process as remote debugging a build. However, you will need to load an extension before navigating to http://localhost:8315/. Both Rancher Desktop and the loaded extension should be listed as available targets.

Debugging dev env with GoLand

The following steps have been tested with GoLand on Linux but might work for other JetBrains IDEs in a similar way.

1. Install the Node.js plugin (via File > Settings > Plugins)

   

2. Go to the "Run/Debug Configurations" dialog (via Run > Edit Configurations...)

3. Add a new Node.js configuration with the following settings:

   • Name: a name for the debug configuration, e.g. rancher desktop
   • Node interpreter: choose your installed node interpreter, e.g. /usr/bin/node
   • Node parameters: scripts/ts-wrapper.js scripts/dev.ts
   • Working directory: choose the working directory of your project, e.g. ~/src/rancher-desktop

   

4. Save the configuration

5. You can now set a breakpoint and click "Debug 'rancher desktop'" to start debugging

   

Development Builds

Windows and macOS

Each commit triggers a GitHub Actions run that results in application bundles (.exes and .dmgs) being uploaded as artifacts. This can be useful if you want to test the latest build of Rancher Desktop as built by the build system. You can download these artifacts from the Summary page of completed package actions.

Linux

Similar to Windows and macOS, Linux builds of Rancher Desktop are made from each commit. However on Linux, only part of the process is done by GitHub Actions. The final part of it is done by Open Build Service.

There are two channels of the Rancher Desktop repositories: dev and stable. stable is the channel that most users use. It is the one that users are instructed to add in the official documentation, and the one that contains builds that are created from official releases. dev is the channel that we are interested in here: it contains builds created from the latest commit made on the main branch, and on any branches that match the format release-*. To learn how to install the development repositories, see below.

When using the dev repositories, it is important to understand the format of the versions of Rancher Desktop available from the dev repositories. The versions are in the format:

<priority>.<branch>.<commit_time>.<commit>

where:

priority is a meaningless number that exists to give versions built from the main branch priority over versions built from the release-* branches when updating.

branch is the branch name; dashes are removed due to constraints imposed by package formats.

commit_time is the UNIX timestamp of the commit used to make the build.

commit is the shortened hash of the commit used to make the build.

.deb Development Repository

You can add the repo with the following steps:

curl -s https://download.opensuse.org/repositories/isv:/Rancher:/dev/deb/Release.key | gpg --dearmor | sudo dd status=none of=/usr/share/keyrings/isv-rancher-dev-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/isv-rancher-dev-archive-keyring.gpg] https://download.opensuse.org/repositories/isv:/Rancher:/dev/deb/ ./' | sudo dd status=none of=/etc/apt/sources.list.d/isv-rancher-dev.list
sudo apt update

You can see available versions with:

apt list -a rancher-desktop

Once you find the version you want to install you can install it with:

sudo apt install rancher-desktop=<version>

This works even if you already have a version of Rancher Desktop installed.

.rpm Development Repository

You can add the repo with:

sudo zypper addrepo https://download.opensuse.org/repositories/isv:/Rancher:/dev/rpm/isv:Rancher:dev.repo
sudo zypper refresh

You can see available versions with:

zypper search -s rancher-desktop

Finally, install the version you want with:

zypper install --oldpackage rancher-desktop=<version>

This works even if you already have a version of Rancher Desktop installed.

Development AppImages

There are no repositories for AppImages, but you can access the latest development AppImage builds here.

API

Rancher Desktop supports a limited HTTP-based API. The API is defined in pkg/rancher-desktop/assets/specs/command-api.yaml, and you can see examples of how it's invoked in the client code at go/src/rdctl.

Stability

The API is currently at version 1, but is still considered internal and experimental, and is subject to change without any advance notice. At some point we expect that necessary changes to the API will go through a warning and deprecation notice.

Contributing

Please see the document about contributing.

Further Reading

Please see the docs directory for further developer documentation.

rancher-desktop's Issues

binaries are auto-linked even when they are on PATH but not in /usr/bin/local

(we have discussed this before)

https://github.com/mattfarina/rd/blob/8c92884da7a60fa8984bb7f501a63ee2afed6e3d/background.js#L197

is looking only at /usr/local/bin

It should probably check the PATH and not auto-link if found. In my case, helm is my in PATH but not in /usr/local/bin so RD ends up masking my helm install with its own.

Add eslint checking via CI

GitHub actions should be find for CI in this case

minikube Bootstrapper field gets set to an empty value

./.minikube/profiles/rancher-desktop/config.json

{
  ...
  Bootstrapper: "",
}

shouldn't happen

Stratos UI

Stratos, the Cloud Foundry UI that can also do Kubernetes and Helm, is a UI we've invested heavily in and that can be built as an electron app. We should look at how to incorporate it into RD. This includes:

• Should we incorporate it with reasons?
• How do we pull it in and make it part of RD?
• Exposing through the menu next to Dashboard
• What elements should be available? Should CF be displayed by default? Is this configurable?

Make sliders work out of the box

The sliders will change the settings in the settings files but RD doesn't apply them. If you restart rancher you get an error that requires running a console command to fix. This should be an intuitive experience.

Package as a Mac app

Setup the toolchain so this application can be built into a Mac App. This does not yet need to be a signed app.

Toggle developer tools in preferences

The developer tools are currently on in preferences by default. This should be a toggle and off by default. It could be a keyboard shortcut or an environment variable. Or, something else.

Local Rancher

A local version of Rancher needs to be running in the environment. This is for a single cluster and does not include multi-cluster management.

Expose kubectl and helm

Through the preference UI, provide checkboxes to symlink kubectl and helm to /usr/local/bin on mac.

The goal of this is to provide the users with access to these tools. Eventually we will have other applications to expose here.

Get the kubectl and helm checkboxes working again

1. The wiring with the Checkbox.vue component broke

2. The link targets are invalid on macos

3. A Promise object is treated like an error.

Move from Homestead to Rancher

We currently install a homestead chart for minimal rancher. This is an in-development project that doesn't appear to be reaching production readiness in the near future. We need to move to using rancher itself instead.

We can start by replacing the the homestead chart tgz file with one from rancher and renaming the release-name to rancher.

Also, the UI calls it minimal rancher and that will need to be changed.

Bundle hyperkit with RD

Factory Reset Button

This is for two use cases:

• As a developer I want to test the fresh install setup. It would be nice to have an easy button for this.
• As a user, I've encountered some problem where my environment is borked. Being about to factory reset could be an option to fix it.

This button would delete the directories created in the library and force RD to restart (is this possible)?

Make linting better

Currently (with #92) we're disabling a bunch of linting rules, because that PR was already big enough. We should go back and turn on various lint rules and fix anything that crops up.

See https://github.com/mattfarina/rd/issues/92#issuecomment-774306004 for a list of things we should consider:

• non-interpolating strings: all single-quotes, double-quotes, or don't care?
  I'd vote for double quotes, since that seems to be the majority of what we have. Also, that's the eslint default.
• missing semicolons
  We should set this to always, because that's what we've been doing.
• I don't get the "missing trailing comma" message -- does json now allow them?
  I have it set at always-multiline: comma on multi-line things (because it makes future diffs better), never otherwise. Also, eslint shouldn't lint JSON?
• indentation
  We have a .editorconfig
• spacing around braces
  I guess we should take eslint defaults here?
• extra = for all comparisons. Should be on because js type promotion can have unexpected results
  Agreed.

Human friendly error messages

The current error messages include exit codes and error messages that are not easy to understand. Exit codes include those of dependencies which are based on other dependencies.

The error messages (in popups) should be human readable with actions one can take if possible.

Provide setting for number of CPUs to use

The default value provided by minikube is a fine default.

The UI for this should be in the Kubernetes preferences. It can be below the existing Kubernetes preferences and before the CLI linking section.

There should be validation on the values here. If a value passed in will cause a problem for minikube we should catch it, inform the user, and not save the setting.

Integrate with existing Rancher telemetry system

Github Rancher Telemetry, tied into Grafana. Similar to a welcome ping.

Default is opt-in, but you can opt-out.

Include first run iso/images in RD

On first run RD downloads elements from the Internet. This can be slow and the first startup time is slow. Can this be packaged into the download and copied to the right place (or linked) on first run to speed up the startup experience.

Support dark mode

The rancher dashboard has a dark mode. It shows, for example, a black body background instead of white. The preferences screens should support dark mode.

Fix linking of binaries

There are two issues with linking Helm and kubectl into the path...

1. It's not discovering paths that were previously linked. See https://github.com/mattfarina/rd/pull/82#pullrequestreview-579679412
2. If you opt-out of linking them into your path they will be re-linked on the next run.

Update language in UI on CLIs linked in

This update would include:

• Adding context about why the tools can't be linked when they can't be
• Adding text to explain what these tools are and what is going on

Verify validity of version # in settings.json before acting on it

If I set the version to something like 1.20.4 it breaks minikube and I have to change it.

Also, the select menu is blank when the proposed current version isn't in the list.

Refactor tray to emit events

I'd like to refactor the menu/tray code so that it's an EventEmitter and we can emit events for the various menu items being clicked. Currently (in #46) I have it emitting events on app, which seems rather wrong.

Show underlying warnings in a dialog box

Similar to 33 - show human friendly messages, relay warning messages back to the user as well.

Enable ingress

Ability to turn off Rancher/Homestead

Rancher installs many components that includes multi-cluster management. A lite version of Rancher (currently dubbed homestead) has numerous features turned off. This is rancher with different configuration to limit it to things like the dashboard (w/o cluster explorer), fleet, authn/z, and the catalog.

In the settings under a new tab on the left for "Rancher" we should have two or possibly more things. We can determine these when we move on this issue.

1. The ability to turn off rancher. This would turn it off (uninstall it with Helm) and cause RD to not launch it when starting a k8s cluster.
2. Provide an option to run full Rancher with all the features. This would be opt-in
3. Possibly provide feature toggles to enable some things and disable others. For example, to enable the UI while disabling fleet. We would do this through passing configuration to the helm install/upgrade commands and the chart. We would expect the underlying features to be in the chart.

Note, if rancher is not installed or the UI is disabled the option in the menu should be removed.

Localization

Currently all messages in the app are English-only. We may want to some day support additional languages.

(Filing this for scheduling & note taking purposes, but not expecting to get around to it any time soon.)

RD on Windows

We need to have RD running on Windows and that includes Windows Home where there is no hypervisor. Instead of a normal hypervisor we should use Windows Subsystem for Linux (likely v2). WSL is available on Windows 10 Home.

With WSL we could either install and manage k3s in an existing Linux or start up a custom Linux setup and expose K3s to windows and the other Linux instances from there. This is open for discussion.

This isn't going to use Minikube as minikube on Windows doesn't work with WSL to manage the things.

Document CONTRIBUTING

include documenting maintainers and the review flow.

Turn rancher logo and status red on error

When kubernetes goes into an error state the status indicator on the tray drop down and the rancher logo should turn red. This will indicate an error.

We should be able to tie this into the events for status.

Preferences should have a version field

This makes it easier for us to do migrations in the future if existing prefs are dropped or renamed.

Still, we should try for full backward- and forward compatibility:

• Ignore any unrecognized prefs
• Never require any fields in a pref block; always supply reasonable defaults.

Make `npm run dev` fast again.

#34 seems to have made npm run dev a bit slower; we should try to see if we can speed it up a bit to make development easier.

We should separate changing minikube settings from restarting it

1. Restarting minikube takes a long time. Better to follow the virtualbox model -- gather the user's settings first, and then act on them after.

Rework kubernetes settings

Add unit testing

RD started as a POC but, as it moves to be a real project it needs testing. A framework needs to be added for testing.

Provide setting for amount of RAM to use

The default value provided by minikube is a fine default.

The UI for this should be in the Kubernetes preferences. It can be below the existing Kubernetes preferences and before the CLI linking section.

There should be validation on the values here. If a value passed in will cause a problem for minikube we should catch it, inform the user, and not save the setting.

Push button expose a service locally

When someone deploys a workload they will often want to access using a port forward. Today you need to know the right kubectl commands to make that happen.

We want to provide a UI that lists workloads and provides a button to create a port forward.

There are numerous details that still need to be worked out such as, is the list just for services or does it include pods?

Expose Rancher Dashboard via Menu

Just like the preferences are able to be open via the menu, The Rancher Dashboard (new Vue UI) should be able to be exposed for the local cluster. This depends on #7.

Can't change the memory size of a running minikube instance

The error message says it needs to be deleted and recreated with the new memory size.

We need a story for supporting this. At the simplest, if this is detected, we can delete it and create and start a new instance.

Add app-level end-to-end testing

Pulling UI-testing out of issue #54 because it's a completely different animal.

Use sliders for some numeric widgets

minikube memory-to-allocate: slider should go from the minimum value (TBD) to the max available on the user's sytem

minikube num-cpus-to-allocate: same thing

• see virtualbox, docker desktop, or other vm management systems to see how they're done.

Depends on issues #47 and #48

Support Apple Silicon

Eventually, we will want to support RD on Apple Silicon. This will likely take a little time and tools are still being ported and our dependencies are being ported. But, this is the top level issue to handle support of that.

k3s fast reset and keep containerd content

When one clicks on the "Reset Kubernetes" button k8s shuts down, the VM is deleted, a new one is created, and k8s is brought back up. This is left over from the way minikube does things by default.

Instead, when the "Reset Kubernetes" button is clicked k3s should be deleted and recreated. containerd should not be reset and images in containerd should stay cached in its location. Note, workloads running in k3s should be killed.

Extra error message trying to stop a non-existent or erroneous minikube

On a pristine machine, with no minikube installed, on shutdown I get an error dialog telling me "Error stopping minikube" . Of course there is, it was never started.

The message should be squelched.

Auto-link kubectl and helm on first run

When RD is first run kubectl and helm should be automatically linked in to /usr/local/bin if it's possible

Add a status bar for secondary messages

Some messages are too important to be hidden in the dev-tools console (or in the shell for the background process), but putting them in a dialog box or notification box is too obtrusive. Best to put them in a status bar where they can be dismissed manually or cleared after a settable delay (which should be a prefs-only field).

Drop the 6GB memory reserve in prefs

Try for the virtual-box way: color the bar red for the last 1GB, and orange for the 3GB before that.

See https://nightcatsama.github.io/vue-slider-component/#/basics/process

Unknown bootstrapper - another new machine issue

When starting up on a new machine:

1. Without running npm run setupmac:

X Exiting due to MK_BOOTSTRAPPER: unknown bootstrapper: k3s

2. After having run npm run setupmac:

X Exiting due to MK_BOOTSTRAPPER: unknown bootstrapper: <empty string>

The dialog box contains a useless long block of code, consisting mostly of the status line 

minikube-v1.17.0.iso: MiB / 212.69 MiB % MiB p/s ETA

repeated over and over without line breaks.

Exception when no kubeconfig can be found

On a new machine, running npm run dev, I get this error message in the console:

(node:15202) UnhandledPromiseRejectionWarning: Error: ENOENT: no such file or directory, watch
    at FSWatcher.start (internal/fs/watchers.js:169:26)
    at Object.watch (fs.js:1343:11)
    at new Tray (/Users/ericp/workspace/rancher/desktop/app/background.js:3916:8)
    at _callee2$ (/Users/ericp/workspace/rancher/desktop/app/background.js:34665:18)
    at tryCatch (/Users/ericp/workspace/rancher/desktop/app/background.js:32119:40)
    at Generator.invoke [as _invoke] (/Users/ericp/workspace/rancher/desktop/app/background.js:32349:22)
    at Generator.next (/Users/ericp/workspace/rancher/desktop/app/background.js:32174:21)
    at asyncGeneratorStep (/Users/ericp/workspace/rancher/desktop/app/background.js:64:24)
    at _next (/Users/ericp/workspace/rancher/desktop/app/background.js:86:9)
    at /Users/ericp/workspace/rancher/desktop/app/background.js:93:7
(node:15202) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). To terminate the node process on unhandled promise rejection, use the CLI flag `--unhandled-rejections=strict` (see https://nodejs.org/api/cli.html#cli_unhandled_rejections_mode). (rejection id: 2)
(node:15202) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

k3s on Mac

The current setup on mac uses minikube and the default image. k3s should be the running Kuberentes. There are a couple possible ways this could be done.

1. Using hyperkit start a VM and then install k3s there. Note, the following 3 requirements are needed for this setup...
   1. Any version of k3s needs to be able to be run.
   2. The setup needs to have the ability to reset the environment to default (wipes out any config changes and all workloads are gone).
   3. Upgrades need to work. For example, one could go from 1.16.8 to 1.18.4 while retaining workloads running in the cluster.
2. Use flags like the --iso-url and registry location to swap out the default minikube environment for k3s.