Add 2 pane layout to "Setting up Codespaces" docs and update IA (#21700)
This commit is contained in:
Amy Burns
@@ -0,0 +1,173 @@
|
||||
---
|
||||
title: Introduction to dev containers
|
||||
intro: 'You can use a `devcontainer.json` file to define a {% data variables.product.prodname_codespaces %} environment for your repository.'
|
||||
allowTitleToDifferFromFilename: true
|
||||
permissions: People with write permissions to a repository can create or edit the codespace configuration.
|
||||
redirect_from:
|
||||
- /github/developing-online-with-github-codespaces/configuring-github-codespaces-for-your-project
|
||||
- /codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project
|
||||
- /github/developing-online-with-codespaces/configuring-codespaces-for-your-project
|
||||
- /codespaces/customizing-your-codespace/configuring-codespaces-for-your-project
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
type: how_to
|
||||
topics:
|
||||
- Codespaces
|
||||
- Set up
|
||||
- Fundamentals
|
||||
product: '{% data reusables.gated-features.codespaces %}'
|
||||
---
|
||||
|
||||
|
||||
|
||||
## About dev containers
|
||||
|
||||
A development container, or dev container, is the environment that {% data variables.product.prodname_codespaces %} uses to provide the tools and runtimes that your project needs for development. If your project does not already have a dev container defined, {% data variables.product.prodname_codespaces %} will use the default configuration, which contains many of the common tools that your team might need for development with your project. For more information, see "[Using the default configuration](#using-the-default-configuration)."
|
||||
|
||||
If you want all users of your project to have a consistent environment that is tailored to your project, you can add a dev container to your repository. You can use a predefined configuration to select a common configuration for various project types with the option to further customize your project or you can create your own custom configuration. For more information, see "[Using a predefined container configuration](#using-a-predefined-container-configuration)" and "[Creating a custom codespace configuration](#creating-a-custom-codespace-configuration)." The option you choose is dependent on the tools, runtimes, dependencies, and workflows that a user might need to be successful with your project.
|
||||
|
||||
{% data variables.product.prodname_codespaces %} allows for customization on a per-project and per-branch basis with a `devcontainer.json` file. This configuration file determines the environment of every new codespace anyone creates for your repository by defining a development container that can include frameworks, tools, extensions, and port forwarding. A Dockerfile can also be used alongside the `devcontainer.json` file in the `.devcontainer` folder to define everything required to create a container image.
|
||||
|
||||
### devcontainer.json
|
||||
|
||||
{% data reusables.codespaces.devcontainer-location %}
|
||||
|
||||
You can use your `devcontainer.json` to set default settings for the entire codespace environment, including the editor, but you can also set editor-specific settings for individual [workspaces](https://code.visualstudio.com/docs/editor/workspaces) in a codespace in a file named `.vscode/settings.json`.
|
||||
|
||||
For information about the settings and properties that you can set in a `devcontainer.json`, see [devcontainer.json reference](https://aka.ms/vscode-remote/devcontainer.json) in the {% data variables.product.prodname_vscode %} documentation.
|
||||
|
||||
### Dockerfile
|
||||
|
||||
A Dockerfile also lives in the `.devcontainer` folder.
|
||||
|
||||
You can add a Dockerfile to your project to define a container image and install software. In the Dockerfile, you can use `FROM` to specify the container image.
|
||||
|
||||
```Dockerfile
|
||||
FROM mcr.microsoft.com/vscode/devcontainers/javascript-node:0-14
|
||||
|
||||
# ** [Optional] Uncomment this section to install additional packages. **
|
||||
# USER root
|
||||
#
|
||||
# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
|
||||
# && apt-get -y install --no-install-recommends <your-package-list-here>
|
||||
#
|
||||
# USER codespace
|
||||
```
|
||||
|
||||
You can use the `RUN` instruction to install any software and `&&` to join commands.
|
||||
|
||||
Reference your Dockerfile in your `devcontainer.json` file by using the `dockerfile` property.
|
||||
|
||||
```json
|
||||
{
|
||||
...
|
||||
"build": { "dockerfile": "Dockerfile" },
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
For more information on using a Dockerfile in a dev container, see [Create a development container](https://code.visualstudio.com/docs/remote/create-dev-container#_dockerfile) in the {% data variables.product.prodname_vscode %} documentation.
|
||||
|
||||
## Using the default configuration
|
||||
|
||||
If you don't define a configuration in your repository, {% data variables.product.prodname_dotcom %} creates a codespace with a base Linux image. The base Linux image includes languages and runtimes like Python, Node.js, JavaScript, TypeScript, C++, Java, .NET, PHP, PowerShell, Go, Ruby, and Rust. It also includes other developer tools and utilities like git, GitHub CLI, yarn, openssh, and vim. To see all the languages, runtimes, and tools that are included use the `devcontainer-info content-url` command inside your codespace terminal and follow the url that the command outputs.
|
||||
|
||||
Alternatively, for more information about everything that is included in the base Linux image, see the latest file in the [`microsoft/vscode-dev-containers`](https://github.com/microsoft/vscode-dev-containers/tree/main/containers/codespaces-linux) repository.
|
||||
|
||||
The default configuration is a good option if you're working on a small project that uses the languages and tools that {% data variables.product.prodname_codespaces %} provides.
|
||||
|
||||
|
||||
## Using a predefined container configuration
|
||||
|
||||
Predefined container definitions include a common configuration for a particular project type, and can help you quickly get started with a configuration that already has the appropriate container options, {% data variables.product.prodname_vscode %} settings, and {% data variables.product.prodname_vscode %} extensions that should be installed.
|
||||
|
||||
Using a predefined configuration is a great idea if you need some additional extensibility. You can also start with a predefined configuration and amend it as needed for your project's setup.
|
||||
|
||||
{% data reusables.codespaces.command-palette-container %}
|
||||
1. Click the definition you want to use.
|
||||
|
||||
1. Follow the prompts to customize your definition. For more information on the options to customize your definition, see "[Adding additional features to your `devcontainer.json` file](#adding-additional-features-to-your-devcontainerjson-file)."
|
||||
1. Click **OK**.
|
||||
|
||||
1. To apply the changes, in the bottom right corner of the screen, click **Rebuild now**. For more information about rebuilding your container, see "[Applying changes to your configuration](#applying-changes-to-your-configuration)."
|
||||
|
||||
|
||||
### Adding additional features to your `devcontainer.json` file
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note:** This feature is in beta and subject to change.
|
||||
|
||||
{% endnote %}
|
||||
|
||||
You can add features to your predefined container configuration to customize which tools are available and extend the functionality of your workspace without creating a custom codespace configuration. For example, you could use a predefined container configuration and add the {% data variables.product.prodname_cli %} as well. You can make these additional features available for your project by adding the features to your `devcontainer.json` file when you set up your container configuration.
|
||||
|
||||
You can add some of the most common features by selecting them when configuring your predefined container. For more information on the available features, see the [script library](https://github.com/microsoft/vscode-dev-containers/tree/main/script-library#scripts) in the `vscode-dev-containers` repository.
|
||||
|
||||
|
||||
|
||||
You can also add or remove features outside of the **Add Development Container Configuration Files** workflow.
|
||||
1. Access the Command Palette (`Shift + Command + P` / `Ctrl + Shift + P`), then start typing "configure". Select **Codespaces: Configure Devcontainer Features**.
|
||||
|
||||
2. Update your feature selections, then click **OK**.
|
||||
|
||||
1. To apply the changes, in the bottom right corner of the screen, click **Rebuild now**. For more information about rebuilding your container, see "[Applying changes to your configuration](#applying-changes-to-your-configuration)."
|
||||
|
||||
|
||||
|
||||
## Creating a custom codespace configuration
|
||||
|
||||
If none of the predefined configurations meet your needs, you can create a custom configuration by adding a `devcontainer.json` file. {% data reusables.codespaces.devcontainer-location %}
|
||||
|
||||
In the file, you can use [supported configuration keys](https://code.visualstudio.com/docs/remote/devcontainerjson-reference) to specify aspects of the codespace's environment, like which {% data variables.product.prodname_vscode %} extensions will be installed.
|
||||
|
||||
{% data reusables.codespaces.vscode-settings-order %}
|
||||
|
||||
You can define default editor settings for {% data variables.product.prodname_vscode %} in two places.
|
||||
|
||||
* Editor settings defined in `.vscode/settings.json` are applied as _Workspace_-scoped settings in the codespace.
|
||||
* Editor settings defined in the `settings` key in `devcontainer.json` are applied as _Remote [Codespaces]_-scoped settings in the codespace.
|
||||
|
||||
After updating the `devcontainer.json` file, you can rebuild the container for your codespace to apply the changes. For more information, see "[Applying changes to your configuration](#applying-changes-to-your-configuration)."
|
||||
|
||||
<!--
|
||||
## Supported codespace configuration keys
|
||||
|
||||
You can use configuration keys supported by {% data variables.product.prodname_codespaces %} in `devcontainer.json`.
|
||||
|
||||
### General settings
|
||||
|
||||
- `name`
|
||||
- `settings`
|
||||
- `extensions`
|
||||
- `forwardPorts`
|
||||
- `postCreateCommand`
|
||||
|
||||
### Docker, Dockerfile, or image settings
|
||||
|
||||
- `image`
|
||||
- `dockerFile`
|
||||
- `context`
|
||||
- `containerEnv`
|
||||
- `remoteEnv`
|
||||
- `containerUser`
|
||||
- `remoteUser`
|
||||
- `mounts`
|
||||
- `runArgs`
|
||||
- `overrideCommand`
|
||||
- `dockerComposeFile`
|
||||
|
||||
For more information about the available settings for `devcontainer.json`, see [devcontainer.json reference](https://aka.ms/vscode-remote/devcontainer.json) in the {% data variables.product.prodname_vscode %} documentation.
|
||||
-->
|
||||
|
||||
## Applying changes to your configuration
|
||||
|
||||
{% data reusables.codespaces.apply-devcontainer-changes %}
|
||||
|
||||
{% data reusables.codespaces.rebuild-command %}
|
||||
1. {% data reusables.codespaces.recovery-mode %} Fix the errors in the configuration.
|
||||
|
||||
- To diagnose the error by reviewing the creation logs, click **View creation log**.
|
||||
- To fix the errors identified in the logs, update your `devcontainer.json` file.
|
||||
- To apply the changes, rebuild your container.
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
title: 'Setting up your project for {% data variables.product.prodname_codespaces %}'
|
||||
title: 'Setting up your repository for {% data variables.product.prodname_codespaces %}'
|
||||
allowTitleToDifferFromFilename: true
|
||||
intro: 'Learn how to get started with {% data variables.product.prodname_codespaces %}, including set up and configuration for specific languages.'
|
||||
product: '{% data reusables.gated-features.codespaces %}'
|
||||
versions:
|
||||
@@ -8,6 +9,8 @@ versions:
|
||||
redirect_from:
|
||||
- /codespaces/getting-started-with-codespaces
|
||||
children:
|
||||
- /configuring-codespaces-for-your-project
|
||||
- /setting-up-your-project-for-codespaces
|
||||
- /setting-up-your-nodejs-project-for-codespaces
|
||||
- /setting-up-your-dotnet-project-for-codespaces
|
||||
- /setting-up-your-java-project-for-codespaces
|
||||
|
||||
@@ -11,6 +11,8 @@ versions:
|
||||
ghec: '*'
|
||||
topics:
|
||||
- Codespaces
|
||||
hasExperimentalAlternative: true
|
||||
hidden: true
|
||||
---
|
||||
|
||||
|
||||
@@ -36,14 +38,14 @@ When you create a codespace, your project is created on a remote VM that is dedi
|
||||
|
||||
You can customize your codespace by adjusting the amount of vCPUs and RAM, [adding dotfiles to personalize your environment](/codespaces/setting-up-your-codespace/personalizing-codespaces-for-your-account), or by modifying the tools and scripts installed.
|
||||
|
||||
{% data variables.product.prodname_codespaces %} uses a file called `devcontainer.json` to store configurations. On launch {% data variables.product.prodname_codespaces %} uses the file to install any tools, dependencies, or other set up that might be needed for the project. For more information, see "[Configuring Codespaces for your project](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
|
||||
{% data variables.product.prodname_codespaces %} uses a file called `devcontainer.json` to store configurations. On launch {% data variables.product.prodname_codespaces %} uses the file to install any tools, dependencies, or other set up that might be needed for the project. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
|
||||
|
||||
|
||||
## Step 2: Add a dev container to your codespace from a template
|
||||
|
||||
The default codespaces container comes with the latest .NET version and common tools preinstalled. However, we encourage you to set up a custom container so you can tailor the tools and scripts that run as part of codespace creation to your project's needs and ensure a fully reproducible environment for all {% data variables.product.prodname_codespaces %} users in your repository.
|
||||
|
||||
To set up your project with a custom container, you will need to use a `devcontainer.json` file to define the environment. In {% data variables.product.prodname_codespaces %} you can add this either from a template or you can create your own. For more information on dev containers, see "[Configuring Codespaces for your project
|
||||
To set up your project with a custom container, you will need to use a `devcontainer.json` file to define the environment. In {% data variables.product.prodname_codespaces %} you can add this either from a template or you can create your own. For more information on dev containers, see "[Introduction to dev containers
|
||||
](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
|
||||
|
||||
|
||||
|
||||
@@ -10,6 +10,8 @@ versions:
|
||||
ghec: '*'
|
||||
topics:
|
||||
- Codespaces
|
||||
hasExperimentalAlternative: true
|
||||
hidden: true
|
||||
---
|
||||
|
||||
|
||||
@@ -35,14 +37,14 @@ When you create a codespace, your project is created on a remote VM that is dedi
|
||||
|
||||
You can customize your codespace by adjusting the amount of vCPUs and RAM, [adding dotfiles to personalize your environment](/codespaces/setting-up-your-codespace/personalizing-codespaces-for-your-account), or by modifying the tools and scripts installed.
|
||||
|
||||
{% data variables.product.prodname_codespaces %} uses a file called `devcontainer.json` to store configurations. On launch {% data variables.product.prodname_codespaces %} uses the file to install any tools, dependencies, or other set up that might be needed for the project. For more information, see "[Configuring Codespaces for your project](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
|
||||
{% data variables.product.prodname_codespaces %} uses a file called `devcontainer.json` to store configurations. On launch {% data variables.product.prodname_codespaces %} uses the file to install any tools, dependencies, or other set up that might be needed for the project. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
|
||||
|
||||
|
||||
## Step 2: Add a dev container to your codespace from a template
|
||||
|
||||
The default codespaces container comes with the latest Java version, package managers (Maven, Gradle), and other common tools preinstalled. However, we recommend that you set up a custom container to define the tools and scripts that your project needs. This will ensure a fully reproducible environment for all {% data variables.product.prodname_codespaces %} users in your repository.
|
||||
|
||||
To set up your project with a custom container, you will need to use a `devcontainer.json` file to define the environment. In {% data variables.product.prodname_codespaces %} you can add this either from a template or you can create your own. For more information on dev containers, see "[Configuring Codespaces for your project](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
|
||||
To set up your project with a custom container, you will need to use a `devcontainer.json` file to define the environment. In {% data variables.product.prodname_codespaces %} you can add this either from a template or you can create your own. For more information on dev containers, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
|
||||
|
||||
|
||||
{% data reusables.codespaces.command-palette-container %}
|
||||
|
||||
@@ -14,6 +14,8 @@ topics:
|
||||
- Developer
|
||||
- Node
|
||||
- JavaScript
|
||||
hasExperimentalAlternative: true
|
||||
hidden: true
|
||||
---
|
||||
|
||||
|
||||
@@ -40,13 +42,13 @@ When you create a codespace, your project is created on a remote VM that is dedi
|
||||
|
||||
You can customize your codespace by adjusting the amount of vCPUs and RAM, [adding dotfiles to personalize your environment](/codespaces/setting-up-your-codespace/personalizing-codespaces-for-your-account), or by modifying the tools and scripts installed.
|
||||
|
||||
{% data variables.product.prodname_codespaces %} uses a file called `devcontainer.json` to store configurations. On launch {% data variables.product.prodname_codespaces %} uses the file to install any tools, dependencies, or other set up that might be needed for the project. For more information, see "[Configuring Codespaces for your project](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
|
||||
{% data variables.product.prodname_codespaces %} uses a file called `devcontainer.json` to store configurations. On launch {% data variables.product.prodname_codespaces %} uses the file to install any tools, dependencies, or other set up that might be needed for the project. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
|
||||
|
||||
## Step 2: Add a dev container to your codespace from a template
|
||||
|
||||
The default codespaces container will support running Node.js projects like [vscode-remote-try-node](https://github.com/microsoft/vscode-remote-try-node) out of the box. By setting up a custom container you can customize the tools and scripts that run as part of codespace creation and ensure a fully reproducible environment for all {% data variables.product.prodname_codespaces %} users in your repository.
|
||||
|
||||
To set up your project with a custom container, you will need to use a `devcontainer.json` file to define the environment. In {% data variables.product.prodname_codespaces %} you can add this either from a template or you can create your own. For more information on dev containers, see "[Configuring Codespaces for your project](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".
|
||||
To set up your project with a custom container, you will need to use a `devcontainer.json` file to define the environment. In {% data variables.product.prodname_codespaces %} you can add this either from a template or you can create your own. For more information on dev containers, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".
|
||||
|
||||
{% data reusables.codespaces.command-palette-container %}
|
||||
3. For this example, click **Node.js**. If you need additional features you can select any container that’s specific to Node or a combination of tools such as Node and MongoDB.
|
||||
|
||||
@@ -0,0 +1,19 @@
|
||||
---
|
||||
title: Adding a dev container to your repository
|
||||
shortTitle: Add a dev container to your repository
|
||||
allowTitleToDifferFromFilename: true
|
||||
intro: 'Get started with your Node.js, Python, .NET, or Java project in {% data variables.product.prodname_codespaces %} by creating a custom dev container.'
|
||||
product: '{% data reusables.gated-features.codespaces %}'
|
||||
versions:
|
||||
fpt: '*'
|
||||
type: tutorial
|
||||
topics:
|
||||
- Codespaces
|
||||
- Developer
|
||||
- Node
|
||||
- JavaScript
|
||||
hasExperimentalAlternative: true
|
||||
interactive: true
|
||||
---
|
||||
|
||||
<!-- This article is specially rendered via the pages/ directory -->
|
||||
@@ -13,6 +13,8 @@ topics:
|
||||
- Codespaces
|
||||
- Developer
|
||||
- Python
|
||||
hasExperimentalAlternative: true
|
||||
hidden: true
|
||||
---
|
||||
|
||||
|
||||
@@ -40,14 +42,14 @@ When you create a codespace, your project is created on a remote VM that is dedi
|
||||
|
||||
You can customize your codespace by adjusting the amount of vCPUs and RAM, [adding dotfiles to personalize your environment](/codespaces/setting-up-your-codespace/personalizing-codespaces-for-your-account), or by modifying the tools and scripts installed.
|
||||
|
||||
{% data variables.product.prodname_codespaces %} uses a file called `devcontainer.json` to store configurations. On launch {% data variables.product.prodname_codespaces %} uses the file to install any tools, dependencies, or other set up that might be needed for the project. For more information, see "[Configuring Codespaces for your project](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
|
||||
{% data variables.product.prodname_codespaces %} uses a file called `devcontainer.json` to store configurations. On launch {% data variables.product.prodname_codespaces %} uses the file to install any tools, dependencies, or other set up that might be needed for the project. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
|
||||
|
||||
|
||||
## Step 2: Add a dev container to your codespace from a template
|
||||
|
||||
The default codespaces container comes with the latest Python version, package managers (pip, Miniconda), and other common tools preinstalled. However, we recommend that you set up a custom container to define the tools and scripts that your project needs. This will ensure a fully reproducible environment for all {% data variables.product.prodname_codespaces %} users in your repository.
|
||||
|
||||
To set up your project with a custom container, you will need to use a `devcontainer.json` file to define the environment. In {% data variables.product.prodname_codespaces %} you can add this either from a template or you can create your own. For more information on dev containers, see "[Configuring Codespaces for your project](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
|
||||
To set up your project with a custom container, you will need to use a `devcontainer.json` file to define the environment. In {% data variables.product.prodname_codespaces %} you can add this either from a template or you can create your own. For more information on dev containers, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
|
||||
|
||||
|
||||
{% data reusables.codespaces.command-palette-container %}
|
||||
|
||||
Reference in New Issue
Block a user