rancher-desktop Documentation

Technical Documentation: rancher-sandbox/rancher-desktop

ℹ️ Provenance: Hybrid Fusion: rancher-sandbox/rancher-desktop (README + 10 In-Tree Chapters) · CodeWiki Reference · Recency: Active (< 180 days)

1. Project Overview & Quickstart (rancher-sandbox/rancher-desktop) Copy Chapter

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 Copy Chapter

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 Copy Chapter

Windows Copy Section

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:

   powershell Copy

   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:

   text Copy

   npm config set msvs_version <visual-studio-version-number>
   npm config set msbuild_path

   For example for Visual Studio 2022:

   text Copy

   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

   text Copy

   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:

   text Copy

   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 v22 is not installed or set as the current version, then install using nvm install 22 and set as current using nvm use 22.xx.xx.
5. Install the yarn package manager via npm install 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:
   text Copy

   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

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 Copy Section

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 22. To install it, run:

nvm install 22.14

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

npm install 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? Copy Section

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

text Copy

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 Copy Section

Ensure you have the following installed:

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

• yarn classic

• Go 1.22 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 Copy Chapter

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

yarn dev

Tests Copy Chapter

To run the unit tests:

yarn test

To run the integration tests:

yarn test:e2e

Building Copy Chapter

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 Copy Section

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 Copy Section

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 Copy Chapter

Windows and macOS Copy Section

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 Copy Section

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:

..<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.

API Copy Chapter

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 Copy Section

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 Copy Chapter

Please see the document about contributing.

Further Reading Copy Chapter

Please see the docs directory for further developer documentation.

2. In-Tree Documentation Chapters (rancher-sandbox/rancher-desktop) Copy Chapter

File: README.md Copy Chapter

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 Copy Chapter

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 Copy Chapter

Windows Copy Section

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:

   powershell Copy

   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:

   text Copy

   npm config set msvs_version <visual-studio-version-number>
   npm config set msbuild_path

   For example for Visual Studio 2022:

   text Copy

   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

   text Copy

   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:

   text Copy

   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 v22 is not installed or set as the current version, then install using nvm install 22 and set as current using nvm use 22.xx.xx.
5. Install the yarn package manager via npm install 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:
   text Copy

   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

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 Copy Section

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 22. To install it, run:

nvm install 22.14

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

npm install 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? Copy Section

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

text Copy

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 Copy Section

Ensure you have the following installed:

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

• yarn classic

• Go 1.22 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 Copy Chapter

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

yarn dev

Tests Copy Chapter

To run the unit tests:

yarn test

To run the integration tests:

yarn test:e2e

Building Copy Chapter

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 Copy Section

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 Copy Section

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 Copy Chapter

Windows and macOS Copy Section

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 Copy Section

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:

..<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.

API Copy Chapter

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 Copy Section

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 Copy Chapter

Please see the document about contributing.

Further Reading Copy Chapter

Please see the docs directory for further developer documentation.

File: bats/README.md Copy Chapter

Overview Copy Chapter

BATS is a testing framework for Bash shell scripts that provides supporting libraries and helpers for customizable test automation.

Setup Copy Chapter

It's important to have a Rancher Desktop CI or release build installed and running with no errors before executing the BATS tests.

On Windows: Copy Section

Clone the Git repository of Rancher Desktop, whether directly inside a WSl distro or on the host Win32.
If the repository will be cloned on Win32, prior to cloning it, it's important to set up the Git configuration by running the following commands:

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

Note that changing crlf settings is not needed when you clone it inside a WSL distro.
Regardless of the repository location, the BATS tests can be executed ONLY from inside a WSL distribution. So, if the repository is cloned on Win32, the repository can be located within a WSL distro from /mnt/c, as it represents the C: drive on Windows.

On Linux: Copy Section

ImageMagick is required to take screenshots on failure.

All platforms: Copy Section

From the root directory of the Git repository, run the following commands to install BATS and its helper libraries into the BATS test directory:

git submodule update --init

Running BATS Copy Chapter

To run the BATS test, specify the path to BATS executable from bats-core and run the following commands:

To run a specific test set from a bats file:

cd bats
./bats-core/bin/bats tests/registry/creds.bats

To run all BATS tests:

cd bats
./bats-core/bin/bats tests/*/

To run the BATS test, specifying some of Rancher Desktop's configuration, run the following commands:

cd bats
RD_CONTAINER_RUNTIME=moby RD_USE_IMAGE_ALLOW_LIST=false ./bats-core/bin/bats tests/registry/creds.bats

There is an experimental subset of BATS tests that pass with an under-construction openSUSE based
distribution; that can be selected via the opensuse tag:

cd bats
./bats-core/bin/bats --filter-tags opensuse tests/*/

On Windows: Copy Section

BATS must be executed from within a WSL distribution. (You have to cd into /mnt/c/REPOSITORY_LOCATION from your unix shell.)

To test the Windows-based tools, set RD_USE_WINDOWS_EXE to true before running.

RD_LOCATION Copy Section

By default bats will use Rancher Desktop installed in a "system" location. If
that doesn't exists, it will try a "user" location, followed by the local "dist"
directory inside the local git directory. The final option if none of the above
apply is to use "dev", which uses yarn dev. On Linux there is no "user"
location.

You can explicitly request a specific install location by setting RD_LOCATION to system, user, dist, or dev:

cd bats
RD_LOCATION=dist ./bats-core/bin/bats ...

RD_NO_MODAL_DIALOGS Copy Section

By default, bats tests are run with the --no-modal-dialogs option so fatal errors are written to background.log,
rather than appearing in a blocking modal dialog box. If you want those dialog boxes, you can specify

cd bats
RD_NO_MODAL_DIALOGS=false ./bats-core/bin/bats ...

The default value for this environment variable is true.

Writing BATS Tests Copy Chapter

1. Add BATS test by creating files with .bats extension under ./bats/tests/FOLDER_NAME
2. A Bats test file is a Bash script with special syntax for defining test cases. BATS syntax and libraries for defining test hooks, writing assertions and treating output can be accessed via BATS documentation:
   • bats-core
   • bats-assert
   • bats-file
   • bats-support

BATS linting Copy Chapter

After finishing to develop a BATS test suite, you can locally verify the syntax and formatting feedback by linting prior to submitting a PR, following the instructions:

1. Make sure to have installed shellcheck and shfmt.

   On macOS:

   • Assuming you have Homebrew:
     sh Copy

     brew install shfmt shellcheck

   • If you have Go installed, you can also install shfmt by running:
     sh Copy

     go install mvdan.cc/sh/v3/cmd/[email protected]

   On Linux:

   • The simplest way to install ShellCheck locally is through your package managers
     such as apt/apt-get/yum. Run commands as per your distro.
     text Copy

     sudo apt install shellcheck

   • shfmt is available as a snap application. If your distribution has snap
     installed, you can install shfmt using the command:
     sh Copy

     sudo snap install shfmt

     The other way to install shfmt is by using the following one-liner command:
     sh Copy

     curl -sS https://webinstall.dev/shfmt | bash

     If you have Go installed, you can also install shfmt by running:
     sh Copy

     go install mvdan.cc/sh/v3/cmd/[email protected]

   On Windows:

   • The simplest way to install shellcheck locally is:

     Via chocolatey:

     powershell Copy

     choco install shellcheck

     Via scoop:

     powershell Copy

     scoop install shellcheck

   • If you have Go installed, you can install shfmt by running:

     powershell Copy

     go install mvdan.cc/sh/v3/cmd/[email protected]

2. Get the syntax and formatting feedback for BATS linting by running from the
   root directory of the Git repository:

   sh Copy

   make -C bats lint

3. Please, make sure to fix the highlighted linting errors prior to submitting
   a PR. You can automatically apply formatting changes suggested by shfmt
   by running the following command:

   sh Copy

   shfmt -w ./bats/tests/containers/factory-reset.bats

Running BATS in CI Copy Chapter

We also run BATS in CI via GitHub Actions; at the time of writing, we do not
yet run them automatically due to failing tests. There are many optional fields
that may be set when triggering a run manually:

Debugging BATS in CI Copy Section

Sometimes we may need to drill down why a test is failing in CI (for example,
when the same test doesn't fail locally). Some things might be helpful:

• Logs for failing runs can be downloaded by clicking on the :file_folder: icon
  in the summary table at the bottom of the run.
• If changes to the application or BATS tests are required, a new package
  action run will need to be manually triggered. In that case, setting sign
  to false in that run will speed it up by a few minutes, by skipping the
  check for properly signed installers — that can be dealt with when the actual
  PR is made.
• When focusing on a particular failing platform, it may be possible to shave
  off a few minutes by setting the package-id field (see above) when starting
  the BATS run; this lets you start the run once the platform you're interested
  in has completed packaging, without waiting for other platforms. This should
  be set to the number after …/actions/runs/ in the URL.
• When testing, it is a good idea to fork the repository and run the tests
  there; this lets you have your own set of GitHub runner quota (which means not
  waiting for PRs other people create). It is not necessary to set owner and
  repo fields when running the BATS action (because it defaults to the
  repository the action is running on). You will, however, need to run the
  package action at least once in your fork.
• It is much faster to specify tests, platforms, and engines to limit
  runs to only the tests you care about; the full run takes somewhere over two
  hours total, even spread out over multiple parallel jobs.

File: docs/networking/windows/rancher-desktop-guest-agent.md Copy Chapter

**[Rancher Desktop Guest Agent](../../../src/go/guestagent)**

The Rancher Desktop Guest Agent operates within the Rancher Desktop WSL distribution, particularly in an isolated namespace when the network tunnel is enabled. It facilitates interactions between various container engine APIs like Moby, containerd, and Kubernetes. The agent monitors container/service creation events from these APIs and, upon detecting ports needing exposure, forwards the port mappings to internal services accordingly. This ensures efficient and automated port forwarding management within the Rancher Desktop environment.

flowchart  LR;
subgraph Host["HOST"]
host-switch["host-switch"]
end
 subgraph VM["WSL"]
  subgraph netNs["Isolated Network Namespace"]
   guest-agent["Guest Agent"]
   docker(("Docker API"))
   containerd(("Containerd API"))
   kubernetes(("K8s API"))
   iptables(("iptable scanning"))
   guest-agent <----> docker
   guest-agent <----> containerd
   guest-agent <----> kubernetes
   guest-agent <----> iptables
   guest-agent ----> host-switch
  end
  subgraph defaultNs["Default Namespace"]
  wsl-proxy["wsl-proxy"]
  end
  guest-agent ----> |UNIX socket| wsl-proxy
 end

Supported Flags Copy Section

• debug: Enables debug logging.

• docker: When this flag is enabled, port mapping via docker API monitoring is enabled. See the port mapping and Docker sections below for details.

• kubernetes: Enables Kubernetes service port forwarding. When enabled, the Rancher Desktop Guest Agent creates a watcher for the Kubernetes API, monitoring NodePort and LoadBalancer services needing port forwarding. For services with exposed ports, the agent creates corresponding port mappings, forwarding them to Rancher Desktop Networking’s host-switch, which hosts an API for exposing ports from the host into the network namespace. If WSL integration is enabled, the port mapping is also forwarded to Rancher Desktop Networking’s wsl-proxy, allowing access from other WSL distributions.

• kubeconfig: Specifies the path to kubeconfig for locating the Kubernetes API endpoint. By default, it looks in /etc/rancher/k3s/k3s.yaml.

• iptables: This flag enables the scanning of iptables. In newer versions of Kubernetes, kubelet no longer creates listeners for NodePort and LoadBalancer services. To rectify this, we manually create those listeners so the port forwarding functions correctly. The guest agent creates a corresponding port mapping that represents the service’s exposed port. The port mapping is then forwarded to Rancher Desktop Networking’s host-switch, which hosts an API for exposing ports from the host into the network namespace. If WSL integration options are enabled within Rancher Desktop, a copy of that port mapping is also forwarded to Rancher Desktop Networking’s wsl-proxy. The wsl-proxy exposes the service port to enable users to access it from other WSL distros.

• containerd: When this flag is enabled, the guest agent monitors container events from the containerd API. It connects to the Containerd API via the containerd socket (/run/k3s/containerd/containerd.sock). Whenever a container is created or deleted, if there are exposed ports associated with that container, the guest agent creates a corresponding port mapping. This port mapping is then forwarded to Rancher Desktop Networking's host-switch, which hosts an API for exposing ports from the host into the network namespace. If WSL integration options are enabled within Rancher Desktop, a copy of this port mapping is also forwarded to Rancher Desktop Networking's wsl-proxy. The wsl-proxy exposes the container's port to enable users to access it from other WSL distros.

• containerdSock: File path for the containerd socket address. If no argument is provided, it defaults to /run/k3s/containerd/containerd.sock.

• vtunnelAddr: Peer address for the Vtunnel process that forwards port mappings to the Vtunnel Host process over AF_VSOCK. This feature will soon be deprecated.

• k8sServiceListenerAddr: Specifies an IP address (0.0.0.0 or 127.0.0.1) to bind Kubernetes services on the host.

• adminInstall: This flag indicates whether Rancher Desktop is installed with administrator privileges. It is used to enable Network Tunnel mode, where port mappings are forwarded to Rancher Desktop Networking's host-switch. The host-switch hosts an API that exposes ports from the host into the network namespace.

• k8sAPIPort: Specifies the Kubernetes API port, which is forwarded to wsl-proxy to allow other distros that are part of WSL integrations to interact via kubectl.

PortMapping Copy Chapter

Is a struct object that represents an exposed container or a service. Portmapping objects consist of the following fields:

type PortMapping struct {
	// Remove indicates whether to remove or add the entry
	Remove bool `json:"remove"`
	// Ports are the port mappings for both IPV4 and IPV6
	Ports nat.PortMap `json:"ports"`
	// ConnectAddrs are the backend addresses to connect to
	ConnectAddrs []ConnectAddrs `json:"connectAddrs"`
}

Networking Mode Copy Chapter

Rancher Desktop Guest Agent can operate in one of two networking modes, depending on startup arguments:

-adminInstall

The Network Tunnel mode allows the Guest Agent to operate in an isolated network namespace with a dedicated iptables. This mode is enabled through Rancher Desktop Networking.

None -adminInstall

Rancher Desktop Guest Agent operates in non-admin user mode. In this mode, all port mappings are bound to localhost, and the use of privileged ports is restricted.

Containerd Copy Chapter

When containerd mode is enabled, the guest agent monitors the containerd API for the following container events:

/tasks/start
/containers/update
/tasks/exit

If it detects any exposed ports associated with a container, it creates a port mapping object. Depending on the selected network mode, the port mapping object is then forwarded to the host. If the privileged service is enabled, it utilizes the vtunnel peer process to communicate the port mappings with privileged services. Alternatively, if network tunnel mode is enabled, it sends the port mappings to the API offered in the host switch process.

If network tunnel mode is enabled along with the WSL integration option, a copy of the port mapping is also forwarded to the WSL proxy process, enabling access to the exposed port from other distributions.

Docker Copy Chapter

Similar to containerd mode, when Docker mode is enabled, the guest agent watches Docker API with the following container events filter:

Filters: filters.NewArgs(
    filters.Arg("type", "container"),
    filters.Arg("event", startEvent),
    filters.Arg("event", stopEvent),
    filters.Arg("event", dieEvent)
),

If it detects any exposed ports associated with a container, it creates a port mapping object. Depending on the selected network mode, the port mapping object is then forwarded to the host. If the privileged service is enabled, it uses the vtunnel peer process to communicate the port mappings with privileged services. Otherwise, if network tunnel mode is enabled, it sends the port mappings to the API offered in the host switch process.

If network tunnel mode is enabled along with the WSL integration option, a copy of the port mapping is also forwarded to the wsl-proxy process, allowing access to the exposed port from other distributions.

Additionally, Docker mode creates a series of iptables rules associated with the PREROUTING and POSTROUTING chains.

The PREROUTING rule rewrites the destination IP address of any packets received by the local system and destined for 192.168.127.2 to 127.0.0.1. Meanwhile, the POSTROUTING chain rule rewrites the source IP address of any packets being sent out through the eth0 network interface to the IP address of that interface (eth0). These rules are necessary because when the port binding is set to 127.0.0.1, an additional DNAT rule is added in the main DOCKER chain after the existing rule using --append.

This adjustment is essential because the initial DOCKER DNAT rule created by Docker only allows traffic to be routed to localhost from localhost. Therefore, an additional rule is added to permit traffic to any destination IP address, enabling the service to be discoverable through the namespaced network's subnet.

These changes are necessary as the traffic is routed via the vm-switch over the tap network. The existing DNAT rule is as follows:

DNAT tcp -- anywhere localhost tcp dpt:9119 to:10.4.0.22:80

The following rule is added after the existing rule:

DNAT tcp -- anywhere anywhere tcp dpt:9119 to:10.4.0.22:80

Kubernetes Copy Chapter

When this option is enabled, the Rancher Desktop guest agent uses the Kubernetes service watcher to subscribe to the Kubernetes API for any services of type NodePort and LoadBalancer that require port exposure. If the service watcher detects such services, it creates a port mapping object representing each service. The port mapping object is then forwarded to the host based on the selected network mode. If the privileged service is enabled, it uses the vtunnel peer process to communicate the port mappings with privileged services. Otherwise, if network tunnel mode is enabled, it sends the port mappings to the API provided in the host switch process.

It is important to note that if the k8sServiceListenerAddr flag is provided, the specified IP address (either 0.0.0.0 or 127.0.0.1) is used to bind the Kubernetes services on the host.

Additionally, if network tunnel mode is enabled along with the WSL integration option, a copy of the port mapping is also forwarded to the wsl-proxy process to allow access to the exposed port from other distributions. However, when the Kubernetes option is enabled, the guest agent statically emits a port mapping to the wsl-proxy process in the default network. This port mapping represents the Kubernetes API port (6443) to allow access to the Kubernetes API from other distributions.

Below port mapping is an example of what is emitted to wsl-proxy:

types.PortMapping {
    Remove: false,
    Ports: nat.PortMap {
        port: [] nat.PortBinding {
            {
                HostIP: "127.0.0.1",
                HostPort: 6443,
            },
        },
    },
}

iptables Copy Chapter

In newer versions of Kubernetes, kubelet no longer automatically creates listeners for NodePort and LoadBalancer services. To address this, we manually create these listeners to ensure proper port forwarding functionality. Service ports requiring forwarding are identified in iptables DNAT. When iptables identifies such ports, it creates a port mapping object representing that service. Depending on the selected network mode, the port mapping object is then forwarded to the host. If the privileged service is enabled, it uses the vtunnel peer process to communicate the port mappings with privileged services. Otherwise, if network tunnel mode is enabled, it sends the port mappings to the API provided by the host switch process.

If network tunnel mode is enabled along with the WSL integration option, a copy of the port mapping is also forwarded to the wsl-proxy process, allowing access to the exposed port from other distributions.

Port forwarding (Network Tunnel) Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

File: docs/networking/windows/rancher-desktop-networking.md Copy Chapter

[Rancher Desktop Networking](../../../src/go/networking/)

Rancher Desktop Networking primarily acts as a layer 2 switch between the host (currently Windows only) and the VM (WSL) using the AF_VSOCK protocol. It facilitates the transmission of Ethernet frames from the VM to the host. Additionally, it provides DNS, DHCP, and dynamic port forwarding functionalities. The Rancher Desktop Networking comprises several key services: host-switch, vm-switch, network-setup, and wsl-proxy. It utilizes gvisor's network stack and draws inspiration from the gvisor-tap-vsock project.

The diagram below demonstrates the overall architecture of Rancher Desktop Networking:

flowchart  LR
subgraph  hostSwitch["host-switch.exe"]
vsockHost{"main loop"}
eth(("reconstruct ETH frames"))
portForwarding["Port Forwarding API"]
end
subgraph  Host["HOST"]
dns["DNS"]
syscall(("OS syscall"))
hostSwitch
end
subgraph  netNs["Isolated Network Namespace"]
vsockVM{"VM Switch"}
tapDevice("eth0")
veth-rd-ns("veth-rd-ns")
containers["containers"]
services["services"]
end
subgraph  WSL["WSL"]
netNs
other-distro(("Other Distros"))
veth-rd-wsl("veth-rd-wsl")
wsl-proxy{"wsl-proxy"}
end
vsockHost  <---->  eth  &  dns
eth  <---->  syscall
vsockHost  ---->  portForwarding
tapDevice  -- ethernet frames -->  vsockVM
veth-rd-ns  -- ethernet frames -->  vsockVM
veth-rd-wsl  <---->  veth-rd-ns
other-distro  <---->  wsl-proxy
wsl-proxy  <---->  veth-rd-wsl
containers  <---->  tapDevice
services  <---->  tapDevice
vsockVM <-- AF_VSOCK ---> vsockHost

host-switch: Copy Chapter

The host-switch runs on the Windows host and acts as a receiver for all traffic originating from the network namespace within the WSL VM. It performs a handshake to identify the correct VM to communicate with over AF_VSOCK. This process retrieves the GUID for the appropriate Hyper-V VM (most likely WSL). It then performs a handshake with the network-setup process running in the WSL distribution to ensure the AF_VSOCK connection is established with the correct VM. Once the ready signal is received from the vm-switch, an AF_VSOCK connection is established to listen for incoming traffic from that VM. Additionally, the host-switch provides a DNS resolver that runs in the user space network and an API for dynamic port forwarding. The port forwarding API offers the following endpoints:

• /services/forwarder/all: Lists all the currently forwarded ports.
• /services/forwarder/expose: Exposes a port.
• /services/forwarder/unexpose: Unexposes a port.

Supported Flags: Copy Chapter

• debug: Enables debug logging.
• subnet: This flag defines a subnet range with a CIDR suffix for a virtual network. If it is not defined, it uses 192.168.127.0/24 as the default range. It is important to note that this value needs to match the subnet flag in the vm-switch.
• port-forward: This is a list of static ports that need to be pre-forwarded to the WSL VM. These ports are not dynamically retrieved from any of the APIs that the Rancher Desktop guest agent interacts with.

network-setup: Copy Chapter

The reason for its creation was that the AF_VSOCK connection could not be established between the host and a process residing inside the network namespace within the VM, as such capability is not currently supported by AF_VSOCK. As a result, the network setup was created. Its main responsibility is to respond to the handshake request from the host-switch.exe. Once the handshake process is successful with the host-switch, the network-setup process creates a new network namespace and attempts to start its subprocess, vm-switch, in the newly created network namespace. It also hands over the AF_VSOCK connection to the vm-switch as a file descriptor in the new namespace.

Additionally, it calls unshare with provided arguments through ---unshare-args. The process also establishes a Virtual Ethernet pair consisting of two endpoints: veth-rd-ns and veth-rd-wsl. veth-rd-wsl resides within the default namespace and is configured to listen on the IP address 192.168.143.2. Conversely, veth-rd-ns is located within a network namespace and is assigned the IP address 192.168.143.1. The virtual Ethernet pair allows accessibility from the default network into the network namespace, which is particularly useful when WSL integration is enabled.

Supported Flags: Copy Chapter

• debug: enable the debug logging

• trace-packets: Forward per-packet tracing to the vm-switch process (see the vm-switch flag below). Off by default; very verbose.

• tap-interface: The name of the tap interface that is created by the vm-switch upon startup, e.g., eth0, eth1. This value is passed to the vm-switch process when the network-setup attempts to start it. If no value is provided, the default name of eth0 is used.

• subnet: A subnet range with a CIDR suffix that is associated with the tap interface in the network namespace. If it is not defined, it uses 192.168.127.0/24 as the default range. It is important to note that this value needs to match the subnet flag in the host-switch.

• tap-mac-address: MAC address associated with the tap interface created by the vm-switch in the network namespace. If no address is provided, the default address of 5a:94:ef:e4:0c:eeis used.

• vm-switch-path: The path to the vm-switch binary that will run in a new namespace. This value is used with nsenter to switch the namespace and start the vm-switch in the network namespace.

• vm-switch-logfile: The path to the logfile for the vm-switch process.

• unshare-arg: The command argument to pass to the unshare program in addition to the following arguments.

• logfile: Path to the logfile for the network-setup process.

vm-switch: Copy Chapter

Once the network-setup starts the vm-switch process in the new namespace, the vm-switch creates a tap device (eth0) and a loopback device (lo). When the eth0 tap device is successfully created, it uses the DHCP client to acquire an IP address within the defined range from the DHCP server. Once the eth0 tap device is up and running, the kernel forwards all raw Ethernet frames originating from the network namespace to the tap device. In addition to the traffic from the network namespace, the kernel also forwards all the traffic that arrives at veth-rd-ns from its pair, veth-rd-wsl, in the default namespace.

The tap device forwards the Ethernet frames over vsock to the host. The process on the host (host-switch.exe) decapsulates the frames. Since host-switch maintains both internal (vm-switch to host-switch.exe) and external (host-switch.exe to the internet) connections, it connects to the external endpoints via syscalls.

Supported Flags: Copy Chapter

• debug: Enable the debug logging

• trace-packets: Log a decoded dump of every packet in both directions. Off by default and deliberately independent of -debug, because it is extremely verbose and writes to vm-switch.log on the data-plane hot path. Enable it at startup by launching Rancher Desktop with RD_VMSWITCH_TRACE=1 in the environment, or toggle it on/off at runtime (without restarting the network stack) by sending SIGUSR1 to the vm-switch process. vm-switch runs in the top-level WSL (init) PID namespace, so signal it from there — e.g. wsl -d rancher-desktop --exec sh -c 'kill -USR1 $(pgrep vm-switch)' — not via rdctl shell, which enters the Rancher Desktop network namespace where vm-switch is not visible.

• tap-interface: Tap interface name to create, eg. eth0, eth1

• tap-mac-address : MAC address that is associated with the tap interface

• subnet: The subnet range with CIDR suffix associated with the tap interface. Although this value is passed from network-setup, it must match the subnet flag in host-switch and network-setup.

• logfile: Path to vm-switch process logfile

wsl-proxy: Copy Chapter

Its primary function comes into play when WSL integration is activated alongside the network tunnel. Running within the default network namespace, it establishes a Unix socket listener (/run/wsl-proxy.sock) for the guest agent process to connect to from inside the network namespace. The guest agent forwards port mappings from various APIs (docker, containerd, and K8s) over the Unix socket to the wsl-proxy. Upon receiving the port mappings, the wsl-proxy sets up listeners bound to localhost for those ports. When traffic arrives at these listeners, it forwards the traffic to the bridge interface connecting the default namespace to the namespaced network, facilitating bidirectional traffic flow.

Supported Flags: Copy Chapter

• debug: Enable the debug logging

• logfile: Path to the logfile for wsl-proxy process

• socketFile: This is the path to the .sock file for the UNIX socket connection established between the Rancher Desktop guest agent and the wsl-proxy. If not provided, the default value of /run/wsl-proxy.sock is used.

• upstreamAddress: This is the IP address associated with the upstream server to use. It corresponds to the address of the veth pair connecting the default namespace to the network namespace, specifically veth-rd-ns. The default value is 192.168.143.1.

Process Timelines: Copy Chapter

Below is a flow chart that demonstrates the process start up orders.

sequenceDiagram
    participant wsl-init (pid n)
    participant network-setup
    participant vm-switch
    participant wsl-init (pid 1)
    participant host-switch.exe
    Note over wsl-init (pid n),wsl-init (pid 1): WSL distro (Network Namespace)
    Note over host-switch.exe: windows host
    wsl-init (pid n)->>network-setup: spawn process
    host-switch.exe->>network-setup: handshake request
    network-setup->>host-switch.exe: handshake response (READY signal)
    host-switch.exe->>network-setup: vsock listener ready
    network-setup->>network-setup: open vsock
    network-setup->>network-setup: create namespace
    network-setup->>network-setup: create veth pair (veth-rd)
    network-setup->>vm-switch: spawn
    Note over network-setup,vm-switch: spawn in network namespace
    Note over network-setup,vm-switch: pass in vsock connection as fd
    network-setup->>wsl-init (pid 1): spawn
    Note over network-setup,wsl-init (pid 1): spawns in netns, new mnt/pid ns
    vm-switch->>vm-switch: create lo/eth0
    vm-switch->>vm-switch: DHCP eth0
    vm-switch->>vm-switch: listen for ethernet frames
    vm-switch->>host-switch.exe: forward ethernet
    wsl-init (pid 1)-->>wsl-init (pid 1): Spawn /sbin/init

File: docs/networking/windows/README.md Copy Chapter

Rancher Desktop Network Documentation

The table of contents below provides references to all the projects that comprise the Rancher Desktop network stack on windows platform.

• Rancher Desktop Guest Agent
• Rancher Desktop Networking

Feature Parity Copy Chapter

Below is table to demonstrate the feature parity between both classic networking and tunneled networking.

File: docs/development/env.md Copy Chapter

Internal Rancher Desktop environment variables

These variables are used for build and development purposes; they are not meant to be set by users.

They do not form an API and may be changed or removed at any time without prior notice.

RD_DEBUG_ENABLED=anything Copy Chapter

Forces debug logging to always be enabled. Useful to debug first-run issues when there is no settings.yaml yet to set debug mode.

RD_FORCE_UPDATES_ENABLED=anything Copy Chapter

When set, it will force auto-update to be enabled even in yarn dev mode. Updates will be checked and downloaded, but not installed.

RD_GITHUB_API_URL=http://localhost:8314 Copy Chapter

Set an alternate GitHub API endpoint, from which the updater fetches the release
it was told about by the upgrade responder. Takes effect only when
RD_FORCE_UPDATES_ENABLED is also set, because the release names both the asset
to download and the checksum that verifies it. Together with
RD_UPGRADE_RESPONDER_URL this lets a test serve a whole release of its own.

RD_MOCK_MACOS_VERSION=semver Copy Chapter

Used for testing compatibility of the app with the OS version, for upgrade responder tests, and for enabling/disabling certain parts of the preferences (related to VZ emulation mode).

RD_UPGRADE_RESPONDER_URL=http://localhost:8314/v1/checkupgrade Copy Chapter

Set an alternate upgrade responder endpoint for testing. Takes effect only when
RD_FORCE_UPDATES_ENABLED is also set, because the responder chooses which
release the updater then goes looking for.

File: docs/development/factory-reset.md Copy Chapter

When rdctl reset --factory is launched from the UI, it writes its stdout into
TMP/rdctl-stdout.txt

where on linux TMP is usually /tmp,

on macOS it's given by $TMPDIR

and on Windows by %TEMP%(command shell) or $env:TEMP(powershell).

This is most useful during development. When the UI runs in debug mode, it spawns rdctl reset --factory with the --verbose option.

We can't write the output into the logs directory as reset --factory deletes it.

File: docs/development/features.md Copy Chapter

Rancher Desktop Features

This document lists the high-level Rancher Desktop features and their current status.

Note:

• Items under the next milestone are targeted for the upcoming monthly release, which usually happens on the 4th Wednesday of the month.
• Items under the later milestone and any spillover items from the next milestone are targeted for the release after.
• Items under the next and later milestones might change based on user feedback, technical challenges, etc.

OS & Platform Support Copy Section

:heavy_check_mark: Win 10/11

:heavy_check_mark: Mac (Intel)

:heavy_check_mark: Mac M1 (apple silicon)

:heavy_check_mark: Linux

:sun_with_face: Linux AArch64

:sun_with_face: Windows on AArch64

:sun_with_face: Windows Containers

Container Engines Copy Section

:heavy_check_mark: Multiple CR support (containerd, dockerd)

Docker Copy Section

:heavy_check_mark: CLI

:heavy_check_mark: Swarm

:heavy_check_mark: Compose

:heavy_check_mark: Docker-only

Kubernetes Copy Section

:heavy_check_mark: K3s bundled

:heavy_check_mark: Multiple versions support

Bundled Tooling Copy Section

:heavy_check_mark: Helm

:sun_with_face: Kubectx

:sun_with_face: kwctl

Image Management Copy Section

:heavy_check_mark: Build, Push, Pull & Scan images

:calendar: Registry Configuration

:sun_with_face: Registry Access Control

Networking Copy Section

:heavy_check_mark: Simple VPN

:calendar: Restricted VPN (Ex: Cisco AnyConnect)

Host Access Copy Section

:sun_with_face: GPU

:sun_with_face: USB

Performance & System Resources Copy Section

:heavy_check_mark: System resource allocation

:sun_with_face: Pause app to save power

Security Copy Section

:heavy_check_mark: Signed builds

:sun_with_face: SBOM generation for images

:sun_with_face: Image Signing

:sun_with_face: Attain SLSA Level

Troubleshooting Copy Section

:heavy_check_mark: View logs

:heavy_check_mark: Partial Reset

:heavy_check_mark: Factory Reset

GUI/Installation Copy Section

:heavy_check_mark: View Containers

:heavy_check_mark: View Images

:heavy_check_mark: Port forwarding

:heavy_check_mark: Auto updates

:heavy_check_mark: Cluster exploration - Rancher Dashboard (Preview)

:heavy_check_mark: Container Exploration

:heavy_check_mark: Container Stats (CPU, memory, network, I/O, processes)

:sun_with_face: Configuration settings

:sun_with_face: Start/Stop/Pause Containers

:sun_with_face: Silent (No-GUI) Install

:sun_with_face: CLI/Headless mode

:calendar: Offline (air gap) mode

:heavy_check_mark: Rancher Desktop CLI aka rdctl (Preview)

IDE Compatibility Copy Section

:heavy_check_mark: VS Code extension (With dockerd(moby))

:sun_with_face: Visual Studio IDE (Needs Validation)

:sun_with_face: Eclipse (Needs Validation)

Integration with Other Rancher Projects Copy Section

:heavy_check_mark: k3s

:calendar: Rancher Dashboard

:sun_with_face: Epinio

:sun_with_face: NeuVector

:sun_with_face: Marketplace

:sun_with_face: Kubewarden

Development Copy Section

:heavy_check_mark: Open source

:heavy_check_mark: Public roadmap

File: docs/development/linux-release-process.md Copy Chapter

Linux Release Process

Note: please read the OBS Tips Documentation
before this document. It includes information that is important to be familiar
with when working with OBS.

When do I need to modify OBS? Copy Chapter

OBS is set up so that you only need to act when you are releasing
a new major or minor version of Rancher Desktop. For example, when
we released 1.11.0 we had to make changes. When we released 1.11.1
nothing had to be done other than the usual checks.

How do I modify OBS when releasing a new major or minor version? Copy Chapter

Before you begin, you must have osc set up. Once you have that done,
you can create a new package for the new major-minor version. Luckily,
we don't have to create a new package from scratch: we can use the
osc copypac command to copy an existing package. This command has
the following signature:

osc copypac   <destination_project> <destination_package>

For example, if we wanted to copy the rancher-desktop-release-1.11
package from the isv:Rancher:dev project to
rancher-desktop-release-1.12, also in the isv:Rancher:dev project,
we would run osc copypac as follows:

osc copypac isv:Rancher:dev rancher-desktop-release-1.11 isv:Rancher:dev rancher-desktop-release-1.12

Once this is done, you must update the _service file and the Meta
tab in the package to refer to the new major-minor version. The
easiest way to do this is via the OBS web interface, which you will
need to be logged into. Generally speaking, you can simply replace
all instances of 1.11 with 1.12 (assuming we're using the above
example). Of course, it is best to understand what you are changing -
the next section will help you with that. Once you have made these
changes, the services will run and the builds should start and
complete successfully.

Finally, you should check the results. This is important - sometimes
the build process falls over, sometimes VMs aren't available to build
your package, and so on. If you run into issues, they are usually
resolved by triggering a rebuild in the web interface. This can
be done by clicking "Trigger Services" in the left navigation bar.
Alternatively, you can trigger a rebuild for a specific package format
by clicking on that package format (i.e. AppImage) from the main page
of the package and then clicking "Trigger rebuild". You will need to
be logged into the web interface to take these actions.

You should also check that the link used to download the "latest"
AppImage actually downloads the latest AppImage - the link is
sometimes not updated, at least, not updated promptly.

How do Linux releases actually *work*? Copy Chapter

The `dev` Channel Copy Section

The dev channel is intended to be used by developers and perhaps
intrepid users. It corresponds to the
isv:Rancher:dev OBS project.

1. A new commit is pushed to a branch of the form main or release-X.Y
   (for example release-1.2 or release-1.11), which triggers the
   package.yml github actions workflow. It builds Rancher Desktop and
   uploads the resultant .zip file to an S3 bucket under a name of the form
   rancher-desktop-linux-.zip.
2. As its last step, the package.yml workflow triggers a service run in
   the OBS package that corresponds to the branch that triggered the workflow
   run.it. This causes OBS to download and unpack the .zip file that was uploaded
   to S3 in step 2. It also causes OBS to pull some files related to the
   package formats will build from the rancher-desktop repository.
3. The new files trigger a build in OBS.
4. Once the build is complete in OBS, the new versions of the packages are
   available to users to download via zypper install, apt install, etc.

The `stable` Channel Copy Section

The stable channel is where actual releases are hosted. It is
intended for use by actual users. The stable channel corresponds
to the
isv:Rancher:stable OBS project.
The stable build process is similar to the dev channel, but works
slightly differently: OBS builds are triggered by published github
releases rather than new commits on branches of a particular format.

1. A new release is published, causing the linux-release.yml github
   actions workflow to run. This workflow fetches the linux .zip file
   from the release, and uploads it to AWS S3 with a name in the format
   rancher-desktop-linux-X.Y.zip (for example, rancher-desktop-linux-1.12.zip).
2. The linux-release.yml workflow triggers a service run in the OBS
   package that corresponds to the major and minor version of the tag
   of the published release. This causes OBS to download and unpack the
   .zip file uploaded to S3 in step 1. It also causes OBS to pull some files
   related to the package formats will build from the rancher-desktop
   repository.
3. The new files trigger a build in OBS.
4. Once the build is complete in OBS, the new versions of the packages are
   available to users to download via zypper install, apt install, etc.

File: docs/development/obs.md Copy Chapter

Tips for Working with OBS

This document contains information on how to use OBS effectively.
If you have not used OBS before, you should read
Getting Started and
Important Concepts first. Then, come back to
the other sections as you begin to work with the relevant parts of OBS.

Getting Started Copy Chapter

The first thing you need to work with OBS is an installation of
openSUSE Leap. Tumbleweed may work, but given its bleeding-edge
nature, Leap is probably a better bet.

The reason you need an installation of openSUSE is because any
real work you do with OBS should be done using the osc command
line tool, which is only available on openSUSE. There is a web
interface, but it lacks much of the functionality that you will need.
Use it for checking on the status of your package, and possibly small
changes, but for everything else use osc.

Important Concepts Copy Chapter

There are a few concepts that one should understand in order to use OBS.
The way they work and interact can be unintuitive at first, so a brief
overview is provided here.

A project is the object in which you do everything in OBS.
Everything falls under projects: repositories, packages, services;
all of these things must belong to a project. Projects may have
subprojects, which are themselves full projects. You have to be an
OBS admin to create a root-level project, so our project (Rancher)
was created as a subproject of the isv root project. Projects are
referred to as each of their parent projects plus their name, all
separated by colons. So to refer to our top-level project, you use
the name isv:Rancher.

A repository is configured on a project. The best way to think of
repositories is in the context of package managers: they are a remote
endpoint from which you can download packages. There are several types of
repositories - some are true repositories in the sense that tools like
apt and dnf can be configured to use them, and others are just endpoints
you can download assets from. Also, you can configure multiple repositories
on each project. This is useful for building and serving packages of multiple
formats from the same binary or source code.

A package is also configured on a project. Conceptually, OBS packages
are different from packages in other contexts. In OBS, a package represents
a set of files that go into a build, such as source files and any package
metadata files (such as rpm .spec files). Also, from the perspective of the
user's package manager, an OBS package represents exactly one version of the
package. So if you want to provide multiple versions of the package in each
repository, you must have one OBS package for each version.

A service is basically a script that can be triggered in a few different
ways. A common use for services is to get the latest version of code from
version control before building and packaging that code. For more information
on services see below; also, you may find the
documentation for services helpful.

Service Tips Copy Chapter

Update your services to the latest versions Copy Section

Before doing anything with services, you should ensure that you have installed
the latest versions of any services you want to work with. This is important
because the remote version of OBS (build.opensuse.org) always uses the latest
version of services - if you are working with a different version on your local
machine, you may run into issues. Also note that services do not always (ever?)
use semantic versioning despite having versions of the form X.Y.Z.

The repositories that openSUSE comes configured with do not contain the latest
versions of the OBS services. In order to get the latest versions you need to
add a repository:

zypper addrepo https://download.opensuse.org/repositories/openSUSE:/Tools/openSUSE_15.3/openSUSE:Tools.repo
zypper refresh

After you do this you can install/update the services you need. If you aren't
on Leap 15.3, you may have to find a different version of this repo, but this
is what works at the time of writing.

How to find out what services are available Copy Section

Services come in the form of rpm packages that can be installed via zypper.
In order to search your installed repos for services, simply run:

zypper search obs-service

How to find out what configuration each service takes Copy Section

Once services are installed you can look at their interface schema in order
to understand how to use them. The interface schema (as well as the source code)
are stored in the directory /usr/lib/obs/service/.

Local Build Tips Copy Chapter

How to get around slow mirrors Copy Section

When you do a local build, the first thing osc does is cache any dependencies
of the build. osc will download these dependencies from mirrors of their
repositories. Unfortunately these mirrors can be very slow. If the dependency
caching step is too slow, you can tell osc build to only fetch packages from
the build.opensuse.org api with the --download-api-only flag.

How to skip running services before build Copy Section

Use the --no-service flag on osc build for this.

How to find the output of a local build Copy Section

When you build locally, it is not always obvious where the output of the build
has been saved. To find the location of your build output, look at the text that
the build has printed at the screen. At the end of it there should be a path;
this is where you can find your built package.

Additional Resources Copy Chapter

• The help-obs and discuss-zypp slack channels are always friendly and helpful.
• The OBS documentation might help resolve any problems you run into.
• The output of osc --help and osc <command> --help may be helpful.
• The Using the Open Build Service may be helpful for understanding
  how we build AppImages using OBS.

--- METRICS ---

• Files Extracted: 11
• Estimated Token Budget: ~19702 tokens
• Recency Window: Active (< 180 days)
• Canonical Reference: https://codewiki.google/github.com/rancher-sandbox/rancher-desktop