Update dev containers content

docs/remote/containers.md

@@ -105,7 +105,7 @@ This quick start covers how to set up a dev container for an existing project to
 
     The list will be automatically sorted based on the contents of the folder you open.
 
-    You may be able to customize your dev container with additional features, which [you can read more about below](#dev-container-features-preview).
+    You may be able to customize your dev container with additional Features, which [you can read more about below](#dev-container-features-preview).
 
     The dev container definitions displayed come from the [vscode-dev-containers repository](https://aka.ms/vscode-dev-containers). You can browse the `containers` folder of that repository to see the contents of each definition.
 
@@ -260,15 +260,15 @@ Selecting the **Remote-Containers: Add Development Container Configuration Files
 
 To learn more about creating `devcontainer.json` files, see [Create a Development Container](/docs/remote/create-dev-container.md).
 
-## Dev container features (preview)
+## Dev Container Features (preview)
 
-Dev container features provide a smooth path for customizing your container definitions.
+Development container "Features" are self-contained, shareable units of installation code and dev container configuration. The name comes from the idea that referencing one of them allows you to quickly and easily add more tooling, runtime, or library "Features" into your development container for you or your collaborators to use.
 
 When you use **Remote-Containers: Add Development Container Configuration Files**, you're presented a list of scripts to customize the existing dev container configurations, such as installing Git or the Azure CLI:
 
-![Dev container features in Command Palette](images/containers/container-features.png)
+![Dev container Features in Command Palette](images/containers/container-features.png)
 
-When you rebuild and reopen in your container, the features you selected will be available in your `devcontainer.json`:
+When you rebuild and reopen in your container, the Features you selected will be available in your `devcontainer.json`:
 
 ```json
 "features": {
@@ -278,27 +278,36 @@ When you rebuild and reopen in your container, the features you selected will be
 
 You'll get IntelliSense when editing the `"features"` property in the `devcontainer.json` directly:
 
-![Intellisense when modifying terraform feature](images/containers/features-intellisense.png)
+![Intellisense when modifying terraform Feature](images/containers/features-intellisense.png)
 
-Built-in features are sourced from the [script library](https://github.com/microsoft/vscode-dev-containers/tree/main/script-library/docs) folder in the vscode-dev-containers repo, but the Remote - Containers extension and GitHub Codespaces include an **early preview** for creating your own dev container features. For example, you can reference these as follows:
+The **Remote-Containers: Configure Container Features** command allows you to update an existing configuration.
+
+The Features sourced in VS Code UI come from the [`devcontainers/features` repository](https://github.com/devcontainers/features).
+
+### Folder structure
+
+A feature is a self contained entity in a folder with at least a `devcontainer-feature.json` and `install.sh` entrypoint script:
 
-```json
-"features": {
-    "your-github-id-or-org/your-repository/[email protected]": "latest"
-}
+```
++-- feature
+|    +-- devcontainer-feature.json
+|    +-- install.sh
+|    +-- (other files)
 ```
 
-The form and format of these custom features is still in flux, but you can try creating your own dev container feature using the [dev-container-features-template](https://github.com/microsoft/dev-container-features-template) sample repository.  Let us know what you think!
+### Features proposal and distribution
 
-The **Remote-Containers: Configure Container Features** command allows you to update an existing configuration.
+Features are an active proposal in the [open dev container specification](https://containers.dev). You can review the [Features proposal](https://github.com/devcontainers/spec/issues/61) and [greater information about how Features work](https://containers.dev/implementors/features/).
+
+You can try creating your own dev container feature using the [feature-template](https://github.com/devcontainers/feature-template) sample repository. There is also [more information about their distribution](https://containers.dev/implementors/features-distribution/) in the spec.
 
 ## Pre-building dev container images
 
 We recommend pre-building images with the tools you need rather than creating and building a container image each time you open your project in a dev container. Using pre-built images will result in a faster container startup,  simpler configuration, and allows you to pin to a specific version of tools to improve supply-chain security and avoid potential breaks. You can automate pre-building your image by scheduling the build using a DevOps or continuous integration (CI) service like GitHub Actions.
 
-We recommend using the [devcontainer CLI](/docs/remote/devcontainer-cli.md) to pre-build your images since it is kept in sync with the Remote - Container extension's latest capabilities - including [dev container features](#dev-container-features-preview). Once you've built your image, you can push it to a container registry (like the [Azure Container Registry](https://docs.microsoft.com/azure/container-registry/container-registry-get-started-docker-cli?tabs=azure-cli), [GitHub Container Registry](https://docs.github.com/packages/working-with-a-github-packages-registry/working-with-the-container-registry#pushing-container-images), or [Docker Hub](https://docs.docker.com/engine/reference/commandline/push)) and reference it directly.
+We recommend using the [devcontainer CLI](/docs/remote/devcontainer-cli.md) to pre-build your images since it is kept in sync with the Remote - Container extension's latest capabilities - including [dev container Features](#dev-container-features-preview). Once you've built your image, you can push it to a container registry (like the [Azure Container Registry](https://docs.microsoft.com/azure/container-registry/container-registry-get-started-docker-cli?tabs=azure-cli), [GitHub Container Registry](https://docs.github.com/packages/working-with-a-github-packages-registry/working-with-the-container-registry#pushing-container-images), or [Docker Hub](https://docs.docker.com/engine/reference/commandline/push)) and reference it directly.
 
-See the [devcontainer CLI article on pre-building images](/docs/remote/devcontainer-cli.md#building-a-dev-container-image) for more information.
+See the [devcontainer CLI article on pre-building images](/docs/remote/devcontainer-cli.md#pre-building) for more information.
 
 ## Inspecting volumes
 
@@ -695,6 +704,12 @@ The following articles may help answer your question:
 * [Docker Desktop for Mac troubleshooting guide](https://docs.docker.com/docker-for-mac/troubleshoot) and [FAQ](https://docs.docker.com/docker-for-mac/faqs/)
 * [Docker Support Resources](https://success.docker.com/article/best-support-resources)
 
+### Can I use dev containers outside of VS Code?
+
+As containerizing production workloads becomes commonplace, dev containers have become broadly useful for scenarios beyond VS Code. We're creating the **Development Containers Specification** to empower anyone in any tool to configure a consistent dev environment. It seeks to find ways to enrich existing formats with common development specific settings, tools, and configuration while still providing a simplified, un-orchestrated single container option – so that they can be used as coding environments or for continuous integration and testing.
+
+You can learn more and review the spec on [containers.dev](https://containers.dev), and you can review active proposals and contribute to the spec in the [devcontainers/spec](https://github.com/devcontainers/spec) repository on GitHub.
+
 ## Questions or feedback
 
 * See [Tips and Tricks](/docs/remote/troubleshooting.md#container-tips) or the [FAQ](/docs/remote/faq.md).
@@ -710,4 +725,4 @@ The following articles may help answer your question:
 * [Attach to a Running Container](/docs/remote/attach-container.md) - Attach to an already running Docker container.
 * [Create a Development Container](/docs/remote/create-dev-container.md) - Create a custom container for your work environment.
 * [Advanced Containers](/remote/advancedcontainers/overview.md) - Find solutions to advanced container scenarios.
-* [devcontainer.json reference](/docs/remote/devcontainerjson-reference.md) - Review the `devcontainer.json` schema.
+* [devcontainer.json reference](https://containers.dev/implementors/json_reference/) - Review the `devcontainer.json` schema.

docs/remote/create-dev-container.md

@@ -489,4 +489,4 @@ The path used for looking up the configuration is derived from the output of `gi
 
 * [Attach to a Running Container](/docs/remote/attach-container.md) - Attach to an already running Docker container.
 * [Advanced Containers](/remote/advancedcontainers/overview.md) - Find solutions to advanced container scenarios.
-* [devcontainer.json reference](/docs/remote/devcontainerjson-reference.md) - Review the `devcontainer.json` schema.
+* [devcontainer.json reference](https://containers.dev/implementors/json_reference/) - Review the `devcontainer.json` schema.

docs/remote/devcontainer-cli.md

@@ -126,13 +126,87 @@ These steps above are also provided in the CLI repo's [README](https://github.co
 
 If you'd like to use the dev container CLI in your CI/CD builds or test automation, you can find examples of GitHub Actions and Azure DevOps Tasks in the [devcontainers/ci](https://github.com/devcontainers/ci) repository.
 
+## Pre-building
+
+The `devcontainer build` command allows you to build quickly build dev container image following the same steps the Remote - Containers extension or GitHub Codespaces will. This is particularly useful when you want to pre-build a dev container image using a CI or DevOps product like GitHub Actions.
+
+`build` accepts a path to the folder containing a `.devcontainer` folder or `.devcontainer.json` file. For example, `devcontainer build --workspace-folder <my_repo>` will build the container image for `my_repo`.
+
+### Example of building and publishing an image
+
+For example, you may want to pre-build a number of images that you then reuse across multiple projects or repositories. To do so, follow these steps:
+
+1. [Create](/docs/editor/versioncontrol.md#initialize-a-repository) a source code repository.
+
+1. Create dev container configuration for each image you want to pre-build, customizing as you wish (including [dev container Features](#dev-container-features-preview)). For example, consider this devcontainer.json file:
+
+    ```json
+    {
+        "build": {
+            "dockerfile": "Dockerfile"
+        },
+        "features": {
+            "docker-in-docker": "latest"
+        }
+    }
+    ```
+
+1. Use the `devcontainer build` command to build the image. See documentation for your image registry (like the [Azure Container Registry](https://docs.microsoft.com/azure/container-registry/container-registry-get-started-docker-cli?tabs=azure-cli), [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#pushing-container-images), or [Docker Hub](https://docs.docker.com/engine/reference/commandline/push)) for information on image naming and additional steps like authentication.
+
+    ```bash
+    devcontainer build --workspace-folder <my_repo>
+    ```
+
+1. Next [push](https://docs.docker.com/engine/reference/commandline/push/) the image to your registry.
+
+    ```bash
+    docker push ghcr.io/your-org/your-image-name
+    ```
+
+1. Finally, for each project or repository that will use your image, craft a simplified devcontainer.json file that either uses the `image` property or references it in a Docker Compose file. Include any dev container features you added in your pre-build configuration in step 2. For example:
+
+    ```json
+    {
+        "image": "ghcr.io/your-org/your-image-name",
+        "features": {
+            "docker-in-docker": "latest"
+        }
+    }
+    ```
+
+That's it!
+
+### [Optional] Avoiding problems with images built using Docker
+
+Given Dockerfiles and Docker Compose files can be used without VS Code or the `devcontainer` CLI, you may want to let users know that they should not try to build the image directly if it will not work as expected. To solve this problem, you can add a build argument that needs to be specified for things to work.
+
+For example, you could add the following to your Dockerfile:
+
+```bash
+ARG vscode
+RUN if [[ -z "$vscode" ]] ; then printf "\nERROR: This Dockerfile needs to be built with VS Code !" && exit 1; else printf "VS Code is detected: $vscode"; fi
+```
+
+And the following in your `devcontainer.json`:
+```json
+"build": {
+      "dockerfile": "Dockerfile",
+      "args": {
+          // set vscode arg for Dockerfile
+          "vscode": "true"
+      },
+    }
+```
+
+In the Docker Compose case, you can add this argument to a separate [override file to extend your configuration](https://github.com/microsoft/vscode-docs/blob/a55ae5b286196b495e2b3ea9f0b3e211beb7c925/docs/remote/create-dev-container.md#extend-your-docker-compose-file-for-development) that is located in a different place in your source tree than the primary Docker Compose file.
+
 ## Feedback
 
 The dev container CLI and specification are under active development and we welcome your feedback, which you can provide in [this issue](https://github.com/devcontainers/cli/issues/7), or through new issues and pull requests in the [devcontainers/cli](https://github.com/devcontainers/cli) repository.
 
 ## Next steps
 
 * [Dev container specification repository](https://github.com/devcontainers/spec) - Read and contribute to the open specification.
-* [devcontainer.json reference](/docs/remote/devcontainerjson-reference.md) - Review the `devcontainer.json` schema.
+* [devcontainer.json reference](https://containers.dev/implementors/json_reference/) - Review the `devcontainer.json` schema.
 * [Create a Development Container](/docs/remote/create-dev-container.md) - Create a custom container for your work environment.
 * [Advanced Containers](/remote/advancedcontainers/overview.md) - Find solutions to advanced container scenarios.