Thanks to visit codestin.com
Credit goes to github.com

Skip to content

docs: add file sync to coder desktop docs #17463

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 10 commits into
base: main
Choose a base branch
from
Open

docs: add file sync to coder desktop docs #17463

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
940bfe6
beta tag; confirm steps
EdwardAngert Apr 17, 2025
749d839
desktop file sync
EdwardAngert Apr 17, 2025
9dd403e
Merge branch 'main' into 16869-desktop-file-sync
EdwardAngert Apr 17, 2025
b1f9356
sync direction and merge conflict resolution
EdwardAngert Apr 21, 2025
c43c528
add status tooltip
EdwardAngert Apr 22, 2025
42e7648
file sync conflicts
EdwardAngert Apr 22, 2025
e02a3ab
Merge branch 'main' into 16869-desktop-file-sync
EdwardAngert Apr 22, 2025
006439a
md images
EdwardAngert May 9, 2025
55c7334
alpha beta
EdwardAngert May 9, 2025
b57d879
Merge branch 'main' into 16869-desktop-file-sync
EdwardAngert May 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added docs/images/user-guides/desktop/coder-desktop-file-sync-add.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/user-guides/desktop/coder-desktop-file-sync-conflicts-mouseover.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/user-guides/desktop/coder-desktop-file-sync-staging.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/user-guides/desktop/coder-desktop-file-sync-watching.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/user-guides/desktop/coder-desktop-file-sync.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/user-guides/desktop/coder-desktop-workspaces.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/manifest.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -193,7 +193,7 @@
"description": "Use Coder Desktop to access your workspace like it's a local machine",
"path": "./user-guides/desktop/index.md",
"icon_path": "./images/icons/computer-code.svg",
"state": ["early access"]
"state": ["beta"]
},
{
"title": "Workspace Management",
Expand Down
84 changes: 68 additions & 16 deletions docs/user-guides/desktop/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Coder Desktop (Early Access)
# Coder Desktop (Beta)

Use Coder Desktop to work on your workspaces as though they're on your LAN, no
port-forwarding required.
Expand All @@ -22,7 +22,7 @@ You can install Coder Desktop on macOS or Windows.

Alternatively, you can manually install Coder Desktop from the [releases page](https://github.com/coder/coder-desktop-macos/releases).

1. Open **Coder Desktop** from the Applications directory. When macOS asks if you want to open it, select **Open**.
1. Open **Coder Desktop** from the Applications directory.

1. The application is treated as a system VPN. macOS will prompt you to confirm with:

Expand Down Expand Up @@ -79,11 +79,11 @@ Before you can use Coder Desktop, you will need to sign in.

## macOS

<Image height="325px" src="../../images/user-guides/desktop/coder-desktop-mac-pre-sign-in.png" alt="Coder Desktop menu before the user signs in" align="center" />
![Coder Desktop menu before the user signs in](../../images/user-guides/desktop/coder-desktop-mac-pre-sign-in.png)

## Windows

<Image height="325px" src="../../images/user-guides/desktop/coder-desktop-win-pre-sign-in.png" alt="Coder Desktop menu before the user signs in" align="center" />
![Coder Desktop menu before the user signs in](../../images/user-guides/desktop/coder-desktop-win-pre-sign-in.png)

</div>

Expand All @@ -97,19 +97,19 @@ Before you can use Coder Desktop, you will need to sign in.

1. In your web browser, you may be prompted to sign in to Coder with your credentials:

<Image height="412px" src="../../images/templates/coder-login-web.png" alt="Sign in to your Coder deployment" align="center" />
![Sign in to your Coder deployment](../../images/templates/coder-login-web.png)

1. Copy the session token to the clipboard:

<Image height="350px" src="../../images/templates/coder-session-token.png" alt="Copy session token" align="center" />
![Copy session token](../../images/templates/coder-session-token.png)

1. Paste the token in the **Session Token** field of the **Sign In** screen, then select **Sign In**:

![Paste the session token in to sign in](../../images/user-guides/desktop/coder-desktop-session-token.png)

1. macOS: Allow the VPN configuration for Coder Desktop if you are prompted.
1. macOS: Allow the VPN configuration for Coder Desktop if you are prompted:

<Image height="350px" src="../../images/user-guides/desktop/mac-allow-vpn.png" alt="Copy session token" align="center" />
![Copy session token](../../images/user-guides/desktop/mac-allow-vpn.png)

1. Select the Coder icon in the menu bar (macOS) or system tray (Windows), and click the **Coder Connect** toggle to enable the connection.

Expand All @@ -129,28 +129,80 @@ While active, Coder Connect will list the workspaces you own and will configure

To copy the `.coder` hostname of a workspace agent, you can click the copy icon beside it.

On macOS you can use `ping6` in your terminal to verify the connection to your workspace:
You can also connect to the SSH server in your workspace using any SSH client, such as OpenSSH or PuTTY:

```shell
ping6 -c 5 your-workspace.coder
ssh your-workspace.coder
```

On Windows, you can use `ping` in a Command Prompt or PowerShell terminal to verify the connection to your workspace:
Any services listening on ports in your workspace will be available on the same hostname. For example, you can access a web server on port `8080` by visiting `http://your-workspace.coder:8080` in your browser.

> [!NOTE]
> Currently, the Coder IDE extensions for VSCode and JetBrains create their own tunnel and do not utilize the Coder Connect tunnel to connect to workspaces.
Comment on lines +140 to +141
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is no longer true if the user is running a Coder deployment of version 2.22 or later. IDE extensions connected to older server versions still have this issue.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Better to remove the note instead of making it more explicit to explain the difference in behaviour.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why's that?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am in favor of simpler docs. Eventually, all users, when upgraded to version 2.22, will be using the Coder Connect tunnels. So IMO its better to leave this out.

Or we can say, as per version 2.22 of Coder IDE, extensions can also make use of the Coder Connect tunnel to improve performance

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
> [!NOTE]
> Currently, the Coder IDE extensions for VSCode and JetBrains create their own tunnel and do not utilize the Coder Connect tunnel to connect to workspaces.
> [!NOTE]
> For Coder versions v2.21.3 and earlier: the Coder IDE extensions for VSCode and JetBrains create their own tunnel and do not utilize the Coder Connect tunnel to connect to workspaces.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@matifali - does this feel like a good balance?

for now, because it's all but the newest version, I think we need to have some indication of who's affected

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's perfect.


### Ping your workspace

<div class="tabs">

### macOS

Use `ping6` in your terminal to verify the connection to your workspace:

```shell
ping -n 5 your-workspace.coder
ping6 -c 5 your-workspace.coder
```

Any services listening on ports in your workspace will be available on the same hostname. For example, you can access a web server on port `8080` by visiting `http://your-workspace.coder:8080` in your browser.
### Windows

You can also connect to the SSH server in your workspace using any SSH client, such as OpenSSH or PuTTY:
Use `ping` in a Command Prompt or PowerShell terminal to verify the connection to your workspace:

```shell
ssh your-workspace.coder
ping -n 5 your-workspace.coder
```

</div>

## Sync a local directory with your workspace

Coder Desktop file sync provides bidirectional synchronization between a local directory and your workspace.
You can work offline, add screenshots to documentation, or use local development tools while keeping your files in sync with your workspace.

1. Create a new local directory.

If you select an existing clone of your repository, Desktop will recognize it as conflicting files.

1. In the Coder Desktop app, select **File sync**.

![Coder Desktop File Sync screen](../../images/user-guides/desktop/coder-desktop-file-sync.png)

1. Select the **+** in the corner to select the local path, workspace, and remote path, then select **Add**:

![Coder Desktop File Sync add paths](../../images/user-guides/desktop/coder-desktop-file-sync-add.png)

1. File sync clones your workspace directory to your local directory, then watches for changes:

![Coder Desktop File Sync watching](../../images/user-guides/desktop/coder-desktop-file-sync-watching.png)

For more information about the current status, hover your mouse over the status.

File sync excludes version control system directories like `.git/` from synchronization, so keep your Git-cloned repository wherever you run Git commands.
This means that if you use an IDE with a built-in terminal to edit files on your remote workspace, that should be the Git clone and your local directory should be for file syncs.

> [!NOTE]
> Currently, the Coder IDE extensions for VSCode and JetBrains create their own tunnel and do not utilize the Coder Connect tunnel to connect to workspaces.
> Coder Desktop uses `alpha` and `beta` to distinguish between the:
>
> - Local directory: `alpha`
> - Remote directory: `beta`

### File sync conflicts

File sync shows a `Conflicts` status when it detects conflicting files.

You can hover your mouse over the status for the list of conflicts:

![Desktop file sync conflicts mouseover](../../images/user-guides/desktop/coder-desktop-file-sync-conflicts-mouseover.png)

If you encounter a synchronization conflict, delete the conflicting file that contains changes you don't want to keep.

## Accessing web apps in a secure browser context

Expand Down
Loading