Add notes for Features that have them (#88)

Co-authored-by: Brigit Murtaugh <brigit.murtaugh@microsoft.com>

src/anaconda/NOTES.md

@@ -0,0 +1,13 @@
+## Using Conda
+
+This Feature includes [the `conda` package manager](https://docs.conda.io/projects/conda/en/latest/index.html). Additional packages installed using Conda will be downloaded from Anaconda or another repository if you configure one. To reconfigure Conda in this container to access an alternative repository, please see information on [configuring Conda channels here](https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/channels.html ).
+
+Access to the Anaconda repository is covered by the [Anaconda Terms of Service](https://legal.anaconda.com/policies/en/?name=terms-of-service), which may require some organizations to obtain a commercial license from Anaconda. **However**, when used with GitHub Codespaces or GitHub Actions, **all users are permitted** to use the Anaconda Repository through the service, including organizations normally required by Anaconda to obtain a paid license for commercial activities. Note that third-party packages may be licensed by their publishers in ways that impact your intellectual property, and are used at your own risk.
+
+## Installing a different version of Python
+
+As covered in the [user FAQ](https://docs.anaconda.com/anaconda/user-guide/faq) for Anaconda, you can install different versions of Python than the one in this image by running the following from a terminal:
+
+```bash
+conda install python=3.7
+```

src/common-utils/NOTES.md

@@ -0,0 +1,12 @@
+## Speeding up the command prompt in large repositories
+
+This script provides a custom command prompt that includes information about the git repository for the current folder. However, with certain large repositories, this can result in a slow command prompt since the required git status command can be slow. To resolve this, you can update a git setting to remove the git portion of the command prompt.
+
+To disable the prompt for the current folder's repository, enter the following in a terminal or add it to your `postCreateCommand` or dotfiles:
+
+```bash
+git config codespaces-theme.hide-status 1
+```
+
+This setting will survive a rebuild since it is applied to the repository rather than the container.
+

src/desktop-lite/NOTES.md

@@ -0,0 +1,64 @@
+## Connecting to the desktop
+
+This feature provides two ways of connecting to the desktop environment it adds. The first is to connect using a web browser. To do so:
+
+1. Forward the noVNC port (`6080` by default) to your local machine using either the `forwardPorts` property in `devcontainer.json` or the user interface in your tool (e.g., you can press <kbd>F1</kbd> or <kbd>Ctrl/Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> and select **Ports: Focus on Ports View** in VS Code to bring it into focus).
+1. Open the ports view in your tool, select the noVNC port, and click the Globe icon.
+1. In the browser that appears, click the **Connect** button and enter the desktop password (`vscode` by default).
+
+You can also connect to the desktop using a [VNC viewer](https://www.realvnc.com/en/connect/download/viewer/). To do so:
+
+1. Connect to the environment from a desktop tool that supports the dev container spec (e.g., VS Code client).
+1. Forward the VNC server port (`5901` by default) to your local machine using either the `forwardPorts` property in `devcontainer.json` or the user interface in your tool (e.g., you can press <kbd>F1</kbd> or <kbd>Ctrl/Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> and select **Ports: Focus on Ports View** in VS Code to bring it into focus).
+1. Start your VNC Viewer and connect to localhost:5901. Note that you may need to bump up the color depth to 24 bits to see full color.
+1. Enter the desktop password (`vscode` by default).
+
+## Customizing Fluxbox
+
+The window manager is installed is [Fluxbox](http://fluxbox.org/). **Right-click** to see the application menu. In addition, any UI-based commands you execute inside the dev container will automatically appear on the desktop.
+
+You can customize the desktop using Fluxbox configuration files. The configuration files are located in the `.fluxbox` folder of the home directory of the user you using to connect to the dev container (`$HOME/.fluxbox`).
+
+If you add custom content to your base image or a Dockerfile in this location, the Feature will automatically use it rather than its default configuration.
+
+See the [Fluxbox menu documentation](http://www.fluxbox.org/help/man-fluxbox-menu.php) for format details. More information on additional customization can be found in Fluxbox's [help](http://www.fluxbox.org/help/) and [general](http://fluxbox.sourceforge.net/docbook/en/html/book1.html) documentation.
+
+## Resolving crashes
+
+If you run into applications crashing, you may need to increase the size of the shared memory space allocated to your container. For example, this will bump it up to 1 GB in `devcontainer.json`:
+
+    ```json
+    "runArgs": ["--shm-size=1g"]
+    ```
+
+    Or using Docker Compose:
+
+    ```yaml
+    services:
+      your-service-here:
+        # ...
+        shm_size: '1gb'
+        # ...
+    ```
+
+## Installing a browser
+
+If you need a browser, you can install **Firefox ESR** by adding the following to `.devcontainer/Dockerfile`:
+
+```Dockerfile
+RUN apt-get update && export DEBIAN_FRONTEND=noninteractive && apt-get install -y firefox-esr
+```
+
+If you want the full version of **Google Chrome** in the desktop:
+
+1. Add the following to `.devcontainer/Dockerfile`
+
+    ```Dockerfile
+    RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+        && curl -sSL https://dl.google.com/linux/direct/google-chrome-stable_current_$(dpkg --print-architecture).deb -o /tmp/chrome.deb \
+        && apt-get -y install /tmp/chrome.deb
+    ```
+
+2. Chrome sandbox support requires you set up and run as a non-root user. The [`debian-common.sh`](common.md) script can do this for you, or you [set one up yourself](https://aka.ms/vscode-remote/containers/non-root). Alternatively, you can start Chrome using `google-chrome --no-sandbox`
+
+That's it!

src/docker-from-docker/NOTES.md

@@ -0,0 +1,27 @@
+## Supporting bind mounts from the workspace folder
+
+A common question that comes up is how you can use `bind` mounts from the Docker CLI from within the a dev container using this Feature (e.g. via `-v`). The trick is that, since you're actually using the Docker engine sitting outside of the container, the filesystem paths will be different than those in the container. You need to use the **host**'s paths instead.
+
+> **Note:** The docker-from-docker approach does not currently enable bind mounting locations outside of the workspace folder.
+
+### GitHub Codespaces
+
+In GitHub Codespaces, the workspace folder should work with bind mounts by default, so no further action is required.
+
+### Remote - Containers
+
+A simple way to do this is to put `${localWorkspaceFolder}` in an environment variable that you then use when doing bind mounts inside the container.
+
+Add the following to `devcontainer.json`:
+
+```json
+"remoteEnv": { "LOCAL_WORKSPACE_FOLDER": "${localWorkspaceFolder}" }
+```
+
+Then reference the env var when running Docker commands from the terminal inside the container.
+
+```bash
+docker run -it --rm -v ${LOCAL_WORKSPACE_FOLDER}:/workspace debian bash
+```
+
+> **Note:** There is no `${localWorkspaceFolder}` when using the **Clone Repository in Container Volume** command ([info](https://github.com/microsoft/vscode-remote-release/issues/6160#issuecomment-1014701007)).

src/kubectl-helm-minikube/NOTES.md

@@ -0,0 +1,12 @@
+## Ingress and port forwarding
+
+When configuring [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) for your Kubernetes cluster, note that by default Kubernetes will bind to a specific interface's IP rather than localhost or all interfaces. This is why you need to use the Kubernetes Node's IP when connecting - even if there's only one Node as in the case of Minikube. Port forwarding in Remote - Containers will allow you to specify `<ip>:<port>` in either the `forwardPorts` property or through the port forwarding UI in VS Code.
+
+However, GitHub Codespaces does not yet support this capability, so you'll need to use `kubectl` to forward the port to localhost. This adds minimal overhead since everything is on the same machine. E.g.:
+
+```bash
+minikube start
+minikube addons enable ingress
+# Run this to forward to localhost in the background
+nohup kubectl port-forward --pod-running-timeout=24h -n ingress-nginx service/ingress-nginx-controller :80 &
+```

src/sshd/NOTES.md

@@ -0,0 +1,62 @@
+## Usage
+
+While the some services automates SSH setup (e.g., when using the GitHub CLI for GitHub Codespaces), this may not be the case for other tools and services. Follow these directions to connect to the dev container from these other tools:
+
+1. Connect to your dev container using a desktop tool or CLI that supports the dev container spec (e.g., VS Code client).
+
+2. The first time you've started the container, you will want to set a password for your user. If running as a user other than root, and you have `sudo` installed:
+
+    ```bash
+    sudo passwd $(whoami)
+    ```
+
+    Or if you are running as root:
+
+    ```bash
+    passwd
+    ```
+
+3. Forward the SSH port (`22` by default) to your local machine using either the `forwardPorts` property in `devcontainer.json` or the user interface in your tool (e.g., you can press <kbd>F1</kbd> or <kbd>Ctrl/Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> and select **Ports: Focus on Ports View** in VS Code to bring it into focus).
+
+4. Use a **local terminal** (or other tool) to connect to it using the command and password from step 2. e.g.
+
+    ```bash
+    ssh -p 2222 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o GlobalKnownHostsFile=/dev/null vscode@localhost
+    ```
+
+    ...where `vscode` above is the user you are running as in the container and `2222` after `-p` is the **local address port** from step 2.
+
+    The “-o” arguments are optional, but will prevent you from getting warnings or errors about known hosts when you do this from multiple containers/codespaces.
+
+5. Next time you connect to your container, just repeat steps 3 and 4 and use the same password you set in step 2.
+
+### Using SSHFS
+
+[SSHFS](https://en.wikipedia.org/wiki/SSHFS) allows you to mount a remote filesystem to your local machine with nothing but a SSH connection. Here's how to use it with a dev container.
+
+1. Follow the steps in the previous section to ensure you can connect to the dev container using the normal `ssh` client.
+
+2. Install a SSHFS client.
+
+    - **Windows:** Install [WinFsp](https://github.com/billziss-gh/winfsp/releases) and [SSHFS-Win](https://github.com/billziss-gh/sshfs-win/releases).
+    - **macOS**: Use [Homebrew](https://brew.sh/) to install: `brew install macfuse gromgit/fuse/sshfs-mac`
+    - **Linux:** Use your native package manager to install your distribution's copy of the sshfs package. e.g. `sudo apt-get update && sudo apt-get install sshfs`
+
+3. Mount the remote filesystem.
+
+    - **macOS / Linux:** Use the `sshfs` command to mount the remote filesystem. The arguments are similar to the normal `ssh` command but with a few additions. For example: 
+
+        ```
+        mkdir -p ~/sshfs/devcontainer
+        sshfs "vscode@localhost:/workspaces" "$HOME/sshfs/devcontainer" -p 2222 -o follow_symlinks -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o GlobalKnownHostsFile=/dev/null -C
+        ```
+        ...where `vscode` above is the user you are running as in the container (e.g. `codespace`, `vscode`, `node`, or `root`) and `2222` after the `-p` is the same local port you used in the `ssh` command in step 1.
+
+    - **Windows:** Press Window+R and enter the following in the "Open" field in the Run dialog: 
+    
+        ```
+        \\sshfs.r\vscode@localhost!2222\workspaces
+        ```
+        ...where `vscode` above is the user you are running as in the container and `2222` after the `!` is the same local port you used in the `ssh` command in the previous seciton.
+
+4. Your dev container's filesystem should now be available in the `~/sshfs/devcontainer` folder on macOS or Linux or in a new explorer window on Windows.