Merge pull request #5587 from microsoft/bamurtaugh/dev-container-aug

Update dev containers content

Author: Greg Van Liew

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,45 +260,58 @@ 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": {
-    "github-cli": "latest"
+    "ghcr.io/devcontainers/features/github-cli:1": {
+            "version": "latest"
+        }
 }
 ```
 
 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.
 
-```json
-"features": {
-    "your-github-id-or-org/your-repository/[email protected]": "latest"
-}
+The Features sourced in VS Code UI come from the [`devcontainers/features` repository](https://github.com/devcontainers/features).
+
+### Creating your own feature
+
+It's also easy to create and publish your own Dev Container Features. Published Features can be stored and shared as [OCI Artifacts](https://github.com/opencontainers/artifacts) from any supporting public or private container registry. You can see the list of current published Features on [containers.dev](https://containers.dev/features.html).
+
+A Feature is a self contained entity in a folder with at least a `devcontainer-feature.json` and `install.sh` entrypoint script:
+
+```
++-- 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!
+See the [latest template](https://github.com/devcontainers/feature-template) for instructions on using the dev container CLI to publish your own public or private Features!
 
-The **Remote-Containers: Configure Container Features** command allows you to update an existing configuration.
+### Features proposal and distribution
+
+Features are an active proposal in the open dev container specification. You can review the [Features proposal](https://github.com/devcontainers/spec/issues/61), along with [greater information about how Features work](https://containers.dev/implementors/features/) and their [distribution](https://containers.dev/implementors/features-distribution/).
 
 ## 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 +708,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 +729,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,76 @@ 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": {
+            "ghcr.io/devcontainers/features/docker-in-docker:1": {
+                 "version": "latest"
+            }
+        }
+    }
+    ```
+
+1. Use the `devcontainer build` command to build the image and [push](https://docs.docker.com/engine/reference/commandline/push/) it to your image registry. 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> --push true --image-name <my_image_name>:<optional_image_version>
+    ```
+
+1. Create a simplified devcontainer.json in repositories where you'd like to use the image - the devcontainer.json should either use the `image` property or reference the image in an associated Docker Compose file. Include any dev container Features you added in your pre-build configuration. For example:
+
+        ```json
+        {
+            "image": "ghcr.io/your-org/your-image-name",
+            "features": {
+                "ghcr.io/devcontainers/features/docker-in-docker:1": {
+                     "version": "latest"
+                 }
+            }
+        }
+        ```
+
+On the other hand, if you only intend to use the pre-built image from one repository, you can use the `cacheFrom` property in devcontainer.json or `cache_from` in a related Docker Compose file instead. This will download the image and treat its image layers like a local cache even if this is the first time you've created the Dockerfile on your machine. Like the option above, be sure to include any dev container Features. For example:
+
+```json
+{
+    "build": {
+        "dockerfile": "Dockerfile",
+        "cacheFrom": "ghcr.io/your-org/your-image-name"
+    },
+    "features": {
+        "ghcr.io/devcontainers/features/docker-in-docker:1": {}
+    }
+}
+
+## 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. You may learn more in the [advanced dev container documentation](../../remote/advancedcontainers/reduce-docker-warnings.md#avoiding-problems-with-images-built-using-docker).
+
 ## 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.