Skip to content
This repository was archived by the owner on Aug 7, 2025. It is now read-only.

Commit 3ef5f59

Browse files
HarshCasperHarshCasper
authored
add docs on rancher desktop (#1631)
1 parent eb6d182 commit 3ef5f59

File tree

1 file changed

+163
-0
lines changed
  • content/en/user-guide/integrations/rancher-desktop

1 file changed

+163
-0
lines changed

‎content/en/user-guide/integrations/rancher-desktop/index.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
---
2+
title: "Rancher Desktop"
3+
linkTitle: "Rancher Desktop"
4+
description: >
5+
Use Rancher Desktop with LocalStack
6+
---
7+
8+
## Introduction
9+
10+
Rancher Desktop is a desktop application that provides a Kubernetes cluster on your local machine.
11+
Rancher Desktop allows you to run Docker containers and Kubernetes clusters without relying on remote or cloud-based systems.
12+
It utilizes `containerd` and `dockerd`, enabling users to easily switch between container runtimes.
13+
14+
By default, the LocalStack CLI launches the LocalStack runtime inside a Docker container.
15+
However, if Docker is not available on your system, you can use Rancher Desktop as a popular alternative to run LocalStack.
16+
17+
## Getting started
18+
19+
To run LocalStack using Rancher Desktop, simply aliasing Docker commands to Rancher Desktop's `dockerd` service may not be sufficient for these reasons:
20+
21+
1. LocalStack depends on `docker-py`, which needs to connect to `/var/run/docker.sock`.
22+
2. Lambda services in LocalStack require the Docker socket at `/var/run/docker.sock` to be mounted into the container.
23+
24+
Depending on your operating system, you may need to make additional configurations to ensure LocalStack runs smoothly with Rancher Desktop.
25+
26+
- [Linux/macOS](#linuxmacos)
27+
- [Rancher Desktop with dockerd](#rancher-desktop-with-dockerd)
28+
- [Rancher Desktop with containerd](#rancher-desktop-with-containerd)
29+
- [Windows](#windows)
30+
31+
These setups enable LocalStack to run smoothly with Rancher Desktop across various operating systems, ensuring compatibility with Docker-based workflows.
32+
33+
### Linux/macOS
34+
35+
{{<alert type="info">}}
36+
### Recommended Settings for Rancher Desktop on macOS
37+
38+
If you're using Rancher Desktop on macOS, particularly on Apple Silicon (M1, M2, etc.), it's crucial to adjust both the emulation engine and the volume-sharing method.
39+
It is recommended to switch to the VZ virtualization engine and use VirtioFS for optimal performance and to avoid permission issues.
40+
Without these adjustments, you may encounter permission issues with volume mounts in LocalStack.
41+
42+
#### Switching Emulation from QEMU to VZ (Apple Virtualization Framework)
43+
44+
For macOS users, Rancher Desktop allows switching from QEMU to the Apple Virtualization Framework (VZ) for virtualization.
45+
Using VZ can enhance performance and resolve permission issues with volume mounts when running LocalStack.
46+
47+
Here’s how to switch from QEMU to VZ:
48+
49+
1. Open Rancher Desktop and navigate to **Settings**.
50+
2. Go to the **Virtual Machine** section.
51+
3. Find the **Virtualization Engine** option, which is set to QEMU by default.
52+
4. Change the setting from `QEMU` to `VZ (Apple Virtualization)`.
53+
5. Restart Rancher Desktop to apply the changes.
54+
55+
#### Changing Volume from Reverse-SSHFS to VirtioFS
56+
57+
By default, Rancher Desktop uses `reverse-sshfs` for mounting volumes inside the virtual machine.
58+
However, you can switch to `VirtioFS` to improve performance and address permission issues.
59+
VirtioFS is a faster and more reliable volume sharing method on macOS.
60+
61+
To switch the volume sharing method from reverse-SSHFS to VirtioFS:
62+
63+
1. Open Rancher Desktop and access the **Settings**.
64+
2. Proceed to the **Virtual Machine** section, where you'll find the volume mount options.
65+
3. Select the **File Sharing** setting and change it from `reverse-sshfs` to `VirtioFS`.
66+
4. Restart Rancher Desktop to implement the changes.
67+
{{</alert>}}
68+
69+
#### Rancher Desktop with dockerd
70+
71+
The simplest way to run LocalStack using Rancher Desktop involves making sure that Rancher Desktop's `dockerd` is active and properly configured.
72+
Rancher Desktop typically places its Docker socket file somewhere under your user directory, such as `~/.rancher-desktop`.
73+
LocalStack, however, expects the Docker socket to be at `/var/run/docker.sock`.
74+
In this scenario, you need to create a symlink from the Rancher Desktop socket to the expected location.
75+
76+
Start Rancher Desktop and verify it is set to use the Docker runtime.
77+
Link the Docker socket with the following command:
78+
79+
{{< command >}}
80+
# 1. Make sure there is no existing socket at /var/run/docker.sock
81+
sudo rm -f /var/run/docker.sock
82+
83+
# 2. Adjust the path if your Rancher Desktop socket is in a different location
84+
$ sudo ln -s /var/run/rancher-desktop-lima/docker.sock /var/run/docker.sock
85+
{{< /command >}}
86+
87+
Start LocalStack using this command:
88+
89+
{{< command >}}
90+
$ DEBUG=1 localstack start --network rancher
91+
{{< /command >}}
92+
93+
#### Rancher Desktop with containerd
94+
95+
If you are using the `containerd` runtime in Rancher Desktop, you'll need to make some additional configurations.
96+
Ensure that the `docker` command is available through Rancher Desktop's setup, or alternatively, use the [`nerdctl` command line interface](https://github.com/containerd/nerdctl).
97+
98+
To start LocalStack with the `containerd` environment, use the following command:
99+
100+
{{< command >}}
101+
$ DEBUG=1 DOCKER_CMD=nerdctl localstack start --network rancher
102+
{{< /command >}}
103+
104+
### Windows
105+
106+
You can run Rancher Desktop on Windows using WSL2 (Windows Subsystem for Linux) with a Docker Compose setup for LocalStack.
107+
108+
Ensure Rancher Desktop is configured to use `dockerd`, and that the Docker socket is accessible in WSL2:
109+
110+
{{< command >}}
111+
$ rancher-desktop settings set --docker
112+
{{< /command >}}
113+
114+
Initialize and start Rancher Desktop:
115+
116+
{{< command >}}
117+
$ rancher-desktop --start
118+
{{< /command >}}
119+
120+
Modify your Docker Compose configuration to work with Rancher Desktop:
121+
122+
{{< tabpane lang="yml" >}}
123+
{{< tab header="Community" lang="yml" >}}
124+
version: "3.8"
125+
services:
126+
localstack:
127+
container_name: "${LOCALSTACK_DOCKER_NAME:-localstack-main}"
128+
image: localstack/localstack
129+
ports:
130+
- "127.0.0.1:4566:4566"
131+
- "127.0.0.1:4510-4559:4510-4559"
132+
networks:
133+
- rancher
134+
environment:
135+
- DEBUG=${DEBUG:-0}
136+
volumes:
137+
- "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack"
138+
- "/var/run/docker.sock:/var/run/docker.sock"
139+
{{< /tab >}}
140+
{{< tab header="Pro" lang="yml" >}}
141+
version: "3.8"
142+
services:
143+
localstack:
144+
container_name: "${LOCALSTACK_DOCKER_NAME:-localstack-main}"
145+
image: localstack/localstack-pro
146+
ports:
147+
- "127.0.0.1:4566:4566"
148+
- "127.0.0.1:4510-4559:4510-4559"
149+
- "0.0.0.0:443:443"
150+
networks:
151+
- rancher
152+
environment:
153+
- LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?}
154+
- DEBUG=${DEBUG:-0}
155+
- PERSISTENCE=${PERSISTENCE:-0}
156+
volumes:
157+
- "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack"
158+
- "/var/run/docker.sock:/var/run/docker.sock"
159+
{{< /tab >}}
160+
{{< /tabpane >}}
161+
162+
Finally, start the services using `docker compose up` or `nerdctl compose up`, depending on your configuration.
163+
This will launch your LocalStack instance configured to interact with Rancher Desktop.

0 commit comments

Comments
 (0)