diff --git a/content/desktop/synchronized-file-sharing.md b/content/desktop/synchronized-file-sharing.md index 5b6e09eb943..098951ce113 100644 --- a/content/desktop/synchronized-file-sharing.md +++ b/content/desktop/synchronized-file-sharing.md @@ -9,7 +9,7 @@ sitemap: false > Synchronized file sharing is an early-access feature. > > If you would like to be considered for Synchronized file sharing testing, you can -> [sign up for the early access program](https://www.docker.com/build-early-access-program/?utm_source=docs). +> [sign up for the early access program](https://www.docker.com/docker-desktop-preview-program/). { .restricted } Synchronized file sharing is an alternative file sharing mechanism powered by [Mutagen](https://mutagen.io/). It provides fast and flexible host-to-VM file sharing by replacing bind mounts with synchronized filesystem caches. @@ -19,42 +19,41 @@ Synchronized file sharing is an alternative file sharing mechanism powered by [M ## Who is it for? For developers who: -- Have large repositories or monorepos with 100 000 files or more totaling hundreds of megabytes or even gigabytes -- Are using virtual filesystems, such as VirtioFS, gRPC FUSE, and osxfs, which are no longer scaling well with their codebases -- Regularly encounter performance limitations -- Don't want to worry about file ownership or spend time resolving conflicting file-ownership information when modifying multiple containers +- Have large repositories or monorepos with 100 000 files or more totaling hundreds of megabytes or even gigabytes. +- Are using virtual filesystems, such as VirtioFS, gRPC FUSE, and osxfs, which are no longer scaling well with their codebases. +- Regularly encounter performance limitations. +- Don't want to worry about file ownership or spend time resolving conflicting file-ownership information when modifying multiple containers. ## How does Synchronized file sharing work? A Synchronized file share behaves just like a virtual file share, but takes advantage of Mutagen's high-performance, low-latency code synchronization engine to create a synchronized cache of the host files on an ext4 filesystem within the Docker Desktop VM. If you make filesystem changes on the host or in the VM’s containers it propagates via bidirectional synchronization. -After creating a file share instance, any container using a bind mount that references a host filesystem location which matches the stated synchronized file share host location, is provided by the Synchronized file sharing feature. Bind mounts that don't satisfy this condition are passed to the normal virtual filesystem bind-mounting mechanism, for example VirtioFS or gRPC-FUSE. +After creating a file share instance, any container using a bind mount that points to a location on the host filesystem matching the specified synchronized file share location, utilizes the Synchronized file sharing feature. Bind mounts that don't satisfy this condition are passed to the normal virtual filesystem bind-mounting mechanism, for example VirtioFS or gRPC-FUSE. > **Important** > > Synchronized file sharing isn't available on WSL or when using Windows containers. { .important } -## Set up +## How to enable Synchronized file sharing Before you get started with Synchronized file sharing, you need to: -- Download and install [Docker Desktop version 4.25](release-notes.md) -- Have a Pro, Team, or Business subscription -- Have a Docker ID that's part of a Docker organization participating in the Early access program +- Download and install [Docker Desktop version 4.25](release-notes.md). +- Have a Pro, Team, or Business subscription. To enable Synchronized file sharing: 1. Sign in to Docker Desktop. -2. Anywhere within the Docker Dashboard, enter the Konami Code which has the key sequence of `up, up, down, down, left, right, left, b, a`. -3. From the list of experimental features, select **Mutagen File Sharing**. -4. At the bottom of the list, select **Go back to dashboard** +2. In **Settings**, navigate to the **File sharing** tab within the **Resources** section. +3. On your keyboard, press and hold the `Shift` key along with the `Command` key (Mac) or `Windows`, then click anywhere within the description text to reveal a pop-up. +4. Select **Restart**. The Docker Dashboard closes. -Synchronized file sharing is now enabled and ready for you to create your first file share instance. +When you re-open the Docker Dashboard, Synchronized file sharing is enabled and ready for you to create your first file share instance. ## Create a file share instance To create a synchronized file share: -1. Navigate to **Settings** within Docker Desktop and then within the **Resource** section, select the **File sharing** tab. +1. In **Settings**, navigate to the **File sharing** tab within the **Resources** section. 2. In the **Synchronized file shares** section, select the **plus** icon. 3. Select a host folder to share. The synchronized file share should initialize and be usable. @@ -70,7 +69,7 @@ When the status indicator displays **Watching for filesystem changes**, your fil The **Synchronized file shares** section displays all your file share instances and provides useful information about each instance including: - The origin of the file share content -- A Status update +- A status update - How much space each file share is using - The number of filesystem entry counts - The number of symbolic links @@ -86,7 +85,7 @@ Some example of things you might want to add to your `.syncignore` file are: - Large dependency directories, for example `node_modules` and `composer` directories (unless you rely on accessing them via a bind mount) - `.git directories` (again, unless you need them) -In general, use your ``.syncignore`` file to exclude items that aren't critical to your workflow, especially those that would be slow to sync or use significant storage. +In general, use your `.syncignore` file to exclude items that aren't critical to your workflow, especially those that would be slow to sync or use significant storage. ## Frequently asked questions @@ -98,18 +97,14 @@ Since Docker [acquired Mutagen](https://www.docker.com/blog/mutagen-acquisition/ - Upon launching Docker Desktop, it can take between 5-10 seconds for Synchronized file sharing to fully initialize. During this window, file share instances display as **Connecting** and any new containers created during this window won't replace bind mounts with Synchronized file sharing. -- `.syncignore` changes won't cause deletion until file share recreation. Files that become ignored due to a modification to ``.syncignore`` are left in place, but no longer update through synchronization. +- `.syncignore` changes won't cause deletion until file share recreation. In other words, files that become ignored due to a modification to `.syncignore` are left in place, but no longer update through synchronization. -- Case conflicts, due to Linux being case-sensitive and macOS/Windows only being case-preserving, display as **File exists** problems in the GUI. These can be ignored. However, if they persist, you can report the issue in the issue in the #docker-eap-sync-file-share Slack channel. +- Case conflicts, due to Linux being case-sensitive and macOS/Windows only being case-preserving, display as **File exists** problems in the GUI. These can be ignored. However, if they persist, you can report the issue. - File share instances mounted into [ECI](hardened-desktop/enhanced-container-isolation/_index.md) containers are currently read-only. - You cannot remove a file share instance during the initial synchronization. You have to wait for it to complete before **Delete** has any effect. -- Synchronized file sharing proactively reports temporary issues, which can result in occasional **Conflict** and **Problem** indicators appearing in the GUI during synchronization. These can be ignored. However, if they persist, you can report the issue in the issue in the #docker-eap-sync-file-share Slack channel. +- Synchronized file sharing proactively reports temporary issues, which can result in occasional **Conflict** and **Problem** indicators appearing in the GUI during synchronization. These can be ignored. However, if they persist, you can report the issue. - If you switch from WSL2 to Hyper-V on Windows, Docker Desktop needs to be fully restarted. - -## Feedback - -Thanks for trying the new Synchronized file sharing feature. Give feedback or report any bugs you may find through the #docker-eap-sync-file-share Slack channel.