Add section on connecting to a remote docker host

docs/remote/containers.md

@@ -621,6 +621,196 @@ See the following examples dev containers for additional information:
 
 * [Kubernetes-Helm](https://aka.ms/vscode-remote/samples/kubernetes-helm) - Includes the Docker CLI, kubectl, and Helm and illustrates how you can use them from inside a dev container to access a local Minikube or Docker provided Kubernetes cluster.
 
+### Using SSH to connect to a remote Docker host
+
+Occasionally you may want to use the Remote - Containers extension to develop inside a container that sits on remote server. While we are looking at ways to optimize this experience, this section will outline how you can achieve this today by attaching to a remote container or using Docker Compose.
+
+**Accessing Docker Remotely**
+
+If you have a remote [Docker Machine](https://docs.docker.com/machine/overview/) running on a remote server, you can work with it from your local machine using the Docker CLI by specifying [environment variables like `DOCKER_HOST`, `DOCKER_CERT_PATH`, `DOCKER_TLS_VERIFY`](https://docs.docker.com/machine/reference/env/) on your local machine to connect to a public TCP port. However, this port is often not exposed publicly since it can have leave the machine vulnerable if not secured properly. (For example, installing Docker CE / Desktop does not open up a port by default.)
+
+A more secure way is to use a SSH tunnel to access the Docker socket as needed. If you have an [OpenSSH compatible SSH client](/docs/remote/troubleshooting.md#installing-a-supported-ssh-client) installed, you can run the following commands in a local terminal / command prompt to start up VS Code so that it connects to the remote SSH host. Replace `user@hostname` with the appropriate remote user and hostname / IP for your server and ensure `code-insiders` is in your path.
+
+On **macOS / Linux**:
+
+```bash
+ssh -NL localhost:23750:/var/run/docker.sock user@hostname &
+export DOCKER_HOST=localhost:23750
+code-insiders
+```
+
+On **Windows**:
+
+```bat
+START ssh -NL localhost:23750:/var/run/docker.sock user@hostname
+SET DOCKER_HOST=localhost:23750
+code-insiders
+```
+
+Note that you may need to [enable `AllowStreamLocalForwarding` in your SSH server's sshd config](https://www.ssh.com/ssh/tunneling/example) for this to work.
+
+At this point, you can [attach to any running container](#attaching-to-running-containers) on the remote host from inside the VS Code instance that was started. Once you are done, you can just shut down the `ssh` process to terminate the tunnel. The environment variables that were set are not global, so you can just bounce VS Code to start working with your local Docker install instead.
+
+**Using devcontainer.json to work with a remote dev container**
+
+Docker does **not** support mounting (binding) your local filesystem into a remote container. Even if it did, this would result in very poor performance. As a result, the best practice is store your source code on the remote machine. There are a few different ways to do this, but the simplest is to **create your remote dev container first**, and then **clone your source code into it**.
+
+In this section we'll walk you through how to convert a local `devcontainer.json` into a remote one. Just follow these steps:
+
+1. Follow the steps above to start up VS Code pointing to the right Docker host.
+2. Create and open an empty folder in VS Code
+3. Run **Remote-Containers: Add Container Configuration File...** from the command palette (`kbstyle(F1)`).
+4. Pick a starting point for your remote container from the list that appears.
+5. What you do next will depend on whether you picked a definition that uses a Dockerfile or Docker Compose.
+
+    **Dockerfile**
+
+    Add a `docker-compose.remote.yml` file into the `.devcontainer` folder with the following contents:
+
+    ```yml
+    version: '3'
+    services:
+      dev-container:
+        build:
+          context: .
+          dockerfile: Dockerfile
+
+        volumes:
+            - ssh-workspace:/ssh-workspace
+
+        command: sleep infinity
+
+      # [Optional] Required for ptrace-based debuggers like C++, Go, and Rust
+      cap_add:
+        - SYS_PTRACE
+      security_opt:
+        - seccomp:unconfined
+
+    volumes:
+      ssh-workspace:
+    ```
+
+    Then alter `.devcontainer/devcontainer.json` as follows:
+
+    ```json
+    {
+        "name": "Your name goes here",
+        "dockerComposeFile": "docker-compose.remote.yml",
+        "service": "dev-container",
+        "workspaceFolder": "/ssh-workspace",
+    }
+    ```
+
+    **Docker Compose**
+
+    Add a `docker-compose.remote.yml` file into the `.devcontainer` folder with the following contents. Replace `SERVICE-NAME-GOES-HERE` with the value of the `service` property in `devcontainer.json`.
+
+    ```yml
+    version: '3'
+    services:
+      SERVICE-NAME-GOES-HERE:
+        volumes:
+            - ssh-workspace:/ssh-workspace
+
+    volumes:
+      ssh-workspace:
+    ```
+
+    Then alter two properties in `.devcontainer/devcontainer.json` as follows:
+
+    ```json
+    "dockerComposeFile": [
+        "docker-compose.yml",
+        "docker-compose.remote.yml"
+    ],
+    "workspaceFolder": "/ssh-workspace"
+    ```
+
+6. Run **Remote-Containers: Reopen Folder in Container** from the command palette (`kbstyle(F1)`).
+
+7. Use ``kbstyle(Ctrl+Shift+`)`` to open a terminal inside the container. You can run `git clone` from here to pull down your source code. You can then use **File > Open... / Open Folder...** to open the cloned repository.
+
+Next time you want to connect to this same container, simply run **Remote-Containers: Open Folder in Container...** and select the same local folder in a VS Code window with `DOCKER_HOST` set.
+
+**[Optional] Using the remote filesystem (bind mount) instead of a volume**
+
+The model above uses a Docker volume to persist the source code. While this will prevent the source code from being deleted when you rebuild, you can also use the remote filesystem instead (assuming you have access). The advantage of this model is that you can clone or interact with the source code from **another terminal window** using SSH. This can also be useful if you've **already got source code on-disk** that you want to open in a container.
+
+Just change the `volumes` section to point to the absolute file path on the remote filesystem where the source code should be kept.
+
+```yml
+version: '3'
+services:
+    dev-container:
+    # ...
+    volumes:
+        - /absolute/path/on/remote/machine/for/source/code:/ssh-workspace
+```
+
+**[Optional] Making the remote source code available locally**
+
+If you store your code in the remote filesystem instead of inside a Docker volume, you can also access the remote code from your local machine using [SSHFS](https://en.wikipedia.org/wiki/SSHFS). You can install SSHFS as follows:
+
+* macOS using [Homebrew](https://brew.sh/): `brew install sshfs`
+* Linux using the native package manager. For Debian/Ubuntu: `sudo apt-get install sshfs`
+* Windows using [Chocolaty](https://chocolatey.org/): `choco install sshfs`
+
+To mount the remote filesystem on **macOS or Linux**, run the following from a local terminal replacing `user@hostname` with the remote user and hostname / IP:
+
+```bash
+export USER_AT_HOST=user@hostname
+sshfs '$USER_AT_HOST:' '$HOME/sshfs' -ovolname='$USER_AT_HOST' -p 22  -o workaround=nonodelay -o transform_symlinks -o idmap=user  -C
+```
+
+While this command is active, the remote machine will be available at `~/sshfs`.
+
+On **Windows**, run the following from the command prompt replacing `user@hostname` with the remote user and hostname / IP:
+
+```bat
+net use /PERSISTENT:NO X: \\sshfs\user@hostname
+```
+
+The remote machine will be available at `X:`. You can disconnect from it by right-clicking on the drive in the File Explorer and clicking  Disconnect.
+
+Note that performance will be significantly slower than working through VS Code, so this is best used for small edits, uploading content, etc. Using something like a local source control tool in this way will be very slow and can cause unforseen problems.
+
+**[Optional] Storing your remote devcontainer.json files on the server**
+
+You can actually store your remote connection `.devcontainer` files on the remote server and access them via SSHFS. Imagine you had the following folder tree on the remote machine:
+
+```text
+📁 /home/your-user-name
+    📁 repos
+        📁 your-repository-here
+            📁 .devcontainer
+            📁 .remote
+                📁 .devcontainer
+```
+
+If you put your remote focused dev container settings described above in `~/repos/your-repository-here/.remote` you can open the remote dev container from this folder using a local mount.
+
+On **Linux/macOS**:
+
+```bash
+export USER_AT_HOST=user@hostname
+sshfs '$USER_AT_HOST:' '$HOME/sshfs' -ovolname='$USER_AT_HOST' -p 22  -o workaround=nonodelay -o transform_symlinks -o idmap=user  -C &
+ssh -NL localhost:23750:/var/run/docker.sock $USER_AT_HOST &
+export DOCKER_HOST=localhost:23750
+code-insiders '$HOME/sshfs/$USER_AT_HOST/repos/your-repository-here/.remote'
+```
+
+On **Windows**:
+
+```bat
+SET USER_AT_HOST=user@hostname
+net use /PERSISTENT:NO X: \\sshfs\%USER_AT_HOST%
+START ssh -NL localhost:23750:/var/run/docker.sock %USER_AT_HOST%
+SET DOCKER_HOST=localhost:23750
+code-insiders "X:\repos\your-repository-here\.remote'
+```
+
+Once VS Code appears with the folder, run **Remote-Containers: Reopen Folder in Container** from the command palette.
+
 ## devcontainer.json  reference
 
 | Property | Type | Description |

docs/remote/ssh.md

@@ -57,7 +57,7 @@ To get started, follow these steps:
 
 3. After a moment, VS Code will connect to the SSH server and set itself up. VS Code will keep you up to date using a progress notification and you can see a detailed log in the `Remote - SSH` output channel.
 
-    > **Note:** If your connection is hanging, you may need to enable TCP forwarding or respond to a server prompt. See [tips and tricks](/docs/remote/troubleshooting.md#troubleshooting-hanging-connections) for details.
+    > **Note:** If your connection is hanging, you may need to enable TCP forwarding or respond to a server prompt. See [tips and tricks](/docs/remote/troubleshooting.md#troubleshooting-hanging-or-failing-connections) for details.
 
 4. After you are connected, you'll be in an empty window. You can then open a folder or workspace on the remote machine using **File > Open...** or **File > Open Workspace...**
 

docs/remote/troubleshooting.md

@@ -115,7 +115,7 @@ If you used PuTTYGen to set up SSH public key authentication for the host you ar
         IdentityFile C:\path\to\your\exported\private\keyfile
     ```
 
-### Troubleshooting hanging connections
+### Troubleshooting hanging or failing connections
 
 If you are running into problems with VS Code hanging while trying to connect (and potentially timing out), there are a few things you can do to try to resolve the issue.