diff --git a/content/manuals/desktop/setup/install/linux/_index.md b/content/manuals/desktop/setup/install/linux/_index.md index df96681291ba..87e15c023fe3 100644 --- a/content/manuals/desktop/setup/install/linux/_index.md +++ b/content/manuals/desktop/setup/install/linux/_index.md @@ -1,16 +1,18 @@ --- -description: Install Docker on Linux with ease using our step-by-step installation +description: + Install Docker on Linux with ease using our step-by-step installation guide covering system requirements, supported platforms, and where to go next. -keywords: linux, docker linux install, docker linux, linux docker installation, docker +keywords: + linux, docker linux install, docker linux, linux docker installation, docker for linux, docker desktop for linux, installing docker on linux, docker download linux, how to install docker on linux, linux vs docker engine, switch docker contexts title: Install Docker Desktop on Linux linkTitle: Linux weight: 60 aliases: -- /desktop/linux/install/ -- /desktop/install/linux-install/ -- /desktop/install/linux/ + - /desktop/linux/install/ + - /desktop/install/linux-install/ + - /desktop/install/linux/ --- > **Docker Desktop terms** @@ -23,9 +25,9 @@ This page contains information about general system requirements, supported plat > [!IMPORTANT] > ->Docker Desktop on Linux runs a Virtual Machine (VM) which creates and uses a custom docker context, `desktop-linux`, on startup. +> Docker Desktop on Linux runs a Virtual Machine (VM) which creates and uses a custom docker context, `desktop-linux`, on startup. > ->This means images and containers deployed on the Linux Docker Engine (before installation) are not available in Docker Desktop for Linux. +> This means images and containers deployed on the Linux Docker Engine (before installation) are not available in Docker Desktop for Linux. > > {{< accordion title=" Docker Desktop vs Docker Engine: What's the difference?" >}} @@ -35,7 +37,7 @@ This page contains information about general system requirements, supported plat Docker Desktop for Linux provides a user-friendly graphical interface that simplifies the management of containers and services. It includes Docker Engine as this is the core technology that powers Docker containers. Docker Desktop for Linux also comes with additional features like Docker Scout and Docker Extensions. -#### Installing Docker Desktop and Docker Engine +### Installing Docker Desktop and Docker Engine Docker Desktop for Linux and Docker Engine can be installed side-by-side on the same machine. Docker Desktop for Linux stores containers and images in an isolated @@ -88,7 +90,7 @@ machine. The current context is indicated with an asterisk (`*`). $ docker context ls NAME DESCRIPTION DOCKER ENDPOINT ... default * Current DOCKER_HOST based configuration unix:///var/run/docker.sock ... -desktop-linux unix:///home//.docker/desktop/docker.sock ... +desktop-linux unix:///home//.docker/desktop/docker.sock ... ``` If you have both Docker Desktop and Docker Engine installed on the same machine, @@ -101,14 +103,15 @@ $ docker context use default default Current context is now "default" ``` - + And use the `desktop-linux` context to interact with Docker Desktop: - + ```console $ docker context use desktop-linux desktop-linux Current context is now "desktop-linux" -``` +``` + Refer to the [Docker Context documentation](/manuals/engine/manage-resources/contexts.md) for more details. {{< /accordion >}} @@ -117,13 +120,12 @@ Refer to the [Docker Context documentation](/manuals/engine/manage-resources/con Docker provides `.deb` and `.rpm` packages for the following Linux distributions and architectures: -| Platform | x86_64 / amd64 | -|:------------------------|:-----------------------:| -| [Ubuntu](ubuntu.md) | ✅ | -| [Debian](debian.md) | ✅ | -| [Red Hat Enterprise Linux (RHEL)](rhel.md) | ✅ | -| [Fedora](fedora.md) | ✅ | - +| Platform | x86_64 / amd64 | +| :----------------------------------------- | :------------: | +| [Ubuntu](ubuntu.md) | ✅ | +| [Debian](debian.md) | ✅ | +| [Red Hat Enterprise Linux (RHEL)](rhel.md) | ✅ | +| [Fedora](fedora.md) | ✅ | An experimental package is available for [Arch](archlinux.md)-based distributions. Docker has not tested or verified the installation. @@ -151,7 +153,6 @@ Docker Desktop for Linux runs a Virtual Machine (VM). For more information on wh ### KVM virtualization support - Docker Desktop runs a VM that requires [KVM support](https://www.linux-kvm.org). The `kvm` module should load automatically if the host has virtualization support. To load the module manually, run: @@ -186,7 +187,6 @@ irqbypass 16384 1 kvm #### Set up KVM device user permissions - To check ownership of `/dev/kvm`, run : ```console @@ -201,13 +201,15 @@ $ sudo usermod -aG kvm $USER Sign out and sign back in so that your group membership is re-evaluated. -## Where to go next +## Using Docker SDKs with Docker Desktop -- Install Docker Desktop for Linux for your specific Linux distribution: - - [Install on Ubuntu](ubuntu.md) - - [Install on Debian](debian.md) - - [Install on Red Hat Enterprise Linux (RHEL)](rhel.md) - - [Install on Fedora](fedora.md) - - [Install on Arch](archlinux.md) +Docker Desktop for Linux uses a per-user socket instead of the system-wide `/var/run/docker.sock`. Docker SDKs and tools that connect directly to the Docker daemon need the `DOCKER_HOST` environment variable set to connect to Docker Desktop. For configuration details, see [How do I use Docker SDKs with Docker Desktop for Linux?](/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md#how-do-i-use-docker-sdks-with-docker-desktop-for-linux). +## Where to go next +- Install Docker Desktop for Linux for your specific Linux distribution: + - [Install on Ubuntu](ubuntu.md) + - [Install on Debian](debian.md) + - [Install on Red Hat Enterprise Linux (RHEL)](rhel.md) + - [Install on Fedora](fedora.md) + - [Install on Arch](archlinux.md) diff --git a/content/manuals/desktop/troubleshoot-and-support/faqs/general.md b/content/manuals/desktop/troubleshoot-and-support/faqs/general.md index 85123e70e783..c1e9101b6783 100644 --- a/content/manuals/desktop/troubleshoot-and-support/faqs/general.md +++ b/content/manuals/desktop/troubleshoot-and-support/faqs/general.md @@ -54,6 +54,8 @@ Docker Desktop Windows users can connect to the Docker Engine through a **named For details, see [Docker Engine API](/reference/api/engine/_index.md). +See the [Linux FAQs](linuxfaqs.md) for Linux specific setup. + ### How do I connect from a container to a service on the host? The host has a changing IP address, or none if you have no network access. diff --git a/content/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md b/content/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md index c9b33869772c..177006de4dbc 100644 --- a/content/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md +++ b/content/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md @@ -5,8 +5,8 @@ title: FAQs for Docker Desktop for Linux linkTitle: Linux tags: [FAQ] aliases: -- /desktop/linux/space/ -- /desktop/faqs/linuxfaqs/ + - /desktop/linux/space/ + - /desktop/faqs/linuxfaqs/ weight: 40 --- @@ -16,32 +16,32 @@ Docker Desktop for Linux runs a Virtual Machine (VM) for the following reasons: 1. To ensure that Docker Desktop provides a consistent experience across platforms. - During research, the most frequently cited reason for users wanting Docker Desktop for Linux was to ensure a consistent Docker Desktop - experience with feature parity across all major operating systems. Utilizing - a VM ensures that the Docker Desktop experience for Linux users will closely - match that of Windows and macOS. + During research, the most frequently cited reason for users wanting Docker Desktop for Linux was to ensure a consistent Docker Desktop + experience with feature parity across all major operating systems. Utilizing + a VM ensures that the Docker Desktop experience for Linux users will closely + match that of Windows and macOS. 2. To make use of new kernel features. - Sometimes we want to make use of new operating system features. Because we control the kernel and the OS inside the VM, we can roll these out to all users immediately, even to users who are intentionally sticking on an LTS version of their machine OS. + Because Docker controls the kernel and the OS inside the VM, Docker can roll these out to all users immediately, even to users who are intentionally sticking on an LTS version of their machine OS. 3. To enhance security. - Container image vulnerabilities pose a security risk for the host environment. There is a large number of unofficial images that are not guaranteed to be verified for known vulnerabilities. Malicious users can push images to public registries and use different methods to trick users into pulling and running them. The VM approach mitigates this threat as any malware that gains root privileges is restricted to the VM environment without access to the host. + Container image vulnerabilities pose a security risk for the host environment. There is a large number of unofficial images that are not guaranteed to be verified for known vulnerabilities. Malicious users can push images to public registries and use different methods to trick users into pulling and running them. The VM approach mitigates this threat as any malware that gains root privileges is restricted to the VM environment without access to the host. - Why not run rootless Docker? Although this has the benefit of superficially limiting access to the root user so everything looks safer in "top", it allows unprivileged users to gain `CAP_SYS_ADMIN` in their own user namespace and access kernel APIs which are not expecting to be used by unprivileged users, resulting in [vulnerabilities](https://www.openwall.com/lists/oss-security/2022/01/18/7). + Why not run rootless Docker? Although this has the benefit of superficially limiting access to the root user so everything looks safer in "top", it allows unprivileged users to gain `CAP_SYS_ADMIN` in their own user namespace and access kernel APIs which are not expecting to be used by unprivileged users, resulting in [vulnerabilities](https://www.openwall.com/lists/oss-security/2022/01/18/7). 4. To provide the benefits of feature parity and enhanced security, with minimal impact on performance. - The VM utilized by Docker Desktop for Linux uses [`VirtioFS`](https://virtio-fs.gitlab.io), a shared file system that allows virtual machines to access a directory tree located on the host. Our internal benchmarking shows that with the right resource allocation to the VM, near native file system performance can be achieved with VirtioFS. + The VM utilized by Docker Desktop for Linux uses [`VirtioFS`](https://virtio-fs.gitlab.io), a shared file system that allows virtual machines to access a directory tree located on the host. Docker's internal benchmarking shows that with the right resource allocation to the VM, near native file system performance can be achieved with VirtioFS. - As such, we have adjusted the default memory available to the VM in Docker Desktop for Linux. You can tweak this setting to your specific needs by using the **Memory** slider within the **Settings** > **Resources** tab of Docker Desktop. + As such, the default memory available to the VM in Docker Desktop for Linux is adjusted. You can tweak this setting to your specific needs by using the **Memory** slider within the **Settings** > **Resources** tab of Docker Desktop. ### How do I enable file sharing? Docker Desktop for Linux uses [VirtioFS](https://virtio-fs.gitlab.io/) as the default (and currently only) mechanism to enable file sharing between the host -and Docker Desktop VM. +and Docker Desktop VM. {{< accordion title="Additional information for Docker Desktop version 4.34 and earlier" >}} @@ -59,7 +59,7 @@ mappings for IDs greater than 0 in the containers. | ID in container | ID on host | | --------------- | -------------------------------------------------------------------------------- | -| 0 (root) | ID of the user running Docker Desktop (e.g. 1000) | +| 0 (root) | ID of the user running Docker Desktop (e.g. 1000) | | 1 | 0 + beginning of ID range specified in `/etc/subuid`/`/etc/subgid` (e.g. 100000) | | 2 | 1 + beginning of ID range specified in `/etc/subuid`/`/etc/subgid` (e.g. 100001) | | 3 | 2 + beginning of ID range specified in `/etc/subuid`/`/etc/subgid` (e.g. 100002) | @@ -95,6 +95,34 @@ ACL (see `setfacl(1)`) for folders shared with the Docker Desktop VM. {{< /accordion >}} +### How do I use Docker SDKs with Docker Desktop for Linux? + +Docker Desktop for Linux uses a per-user socket located at `~/.docker/desktop/docker.sock` instead of the system-wide `/var/run/docker.sock`. The Docker CLI handles this automatically through the `desktop-linux` context, but Docker SDKs and other tools that connect directly to the Docker daemon also need the `DOCKER_HOST` environment variable set. + +Without setting `DOCKER_HOST`, SDKs attempt to connect to `/var/run/docker.sock` and fail with an error like: + +```text +Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running? +``` + +To fix this, set the `DOCKER_HOST` environment variable before running your SDK-based application: + +```console +export DOCKER_HOST=unix://$HOME/.docker/desktop/docker.sock +``` + +Or dynamically retrieve it from the `desktop-linux` context: + +```console +export DOCKER_HOST=$(docker context inspect desktop-linux --format '{{ .Endpoints.docker.Host }}') +``` + +To make this permanent, add the export command to your shell profile (`~/.bashrc`, `~/.zshrc`, or similar): + +```console +echo 'export DOCKER_HOST=unix://$HOME/.docker/desktop/docker.sock' >> ~/.bashrc +``` + ### Where does Docker Desktop store Linux containers? Docker Desktop stores Linux containers and images in a single, large "disk image" file in the Linux filesystem. This is different from Docker on Linux, which usually stores containers and images in the `/var/lib/docker` directory on the host's filesystem. @@ -117,7 +145,7 @@ If the disk image file is too large, you can: To move the disk image file to a different location: -1. Select **Settings** then **Advanced** from the **Resources** tab. +1. Select **Settings** then **Advanced** from the **Resources** tab. 2. In the **Disk image location** section, select **Browse** and choose a new location for the disk image. diff --git a/content/reference/api/engine/sdk/_index.md b/content/reference/api/engine/sdk/_index.md index e66b7774a030..5c45cafff268 100644 --- a/content/reference/api/engine/sdk/_index.md +++ b/content/reference/api/engine/sdk/_index.md @@ -44,6 +44,17 @@ For more information, see [Go client reference](https://pkg.go.dev/github.com/mo For more information, see [Docker Engine Python SDK reference](https://docker-py.readthedocs.io/). +> [!NOTE] +> Docker Desktop for Linux users +> +> Docker Desktop for Linux uses a per-user socket instead of the system-wide `/var/run/docker.sock`. To use Docker SDKs with Docker Desktop for Linux, set the `DOCKER_HOST` environment variable: +> +> ```bash +> export DOCKER_HOST=unix://$HOME/.docker/desktop/docker.sock +> ``` +> +> For more details, see [the Linux FAQs](/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md#how-do-i-use-docker-sdks-with-docker-desktop-for-linux). + ## View the API reference You can