jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-23 11:54:18 -05:00
Code Issues Projects Releases Wiki Activity

Add 2 pane layout to "Setting up Codespaces" docs and update IA (#21700)

Browse Source
This commit is contained in:
Amy Burns
2021-11-24 14:41:30 -05:00
committed by GitHub
parent cfa19c157c
commit c3bc538cd4
49 changed files with 1409 additions and 1197 deletions
Download Patch File Download Diff File Expand all files Collapse all files

304
components/playground/content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces/dotnet.tsx Normal file
View File

@@ -0,0 +1,304 @@
import dedent from 'ts-dedent'
import { PlaygroundArticleT } from 'components/playground/types'
const article: PlaygroundArticleT = {
title: 'Add a dev container to your project',
shortTitle: 'C# Codespaces',
topics: ['Codespaces', 'Developer', 'Organization'],
type: 'tutorial',
slug: '/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces',
originalArticle:
'/codespaces/setting-up-your-project-for-codespaces/setting-up-your-dotnet-project-for-codespaces',
codeLanguageId: 'dotnet',
intro: dedent`
This guide shows you how to add a [dev container](/codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project) to define the Codespaces configuration for your **C# (.NET)** project. For other project languages, click the language button to the right.
`,
prerequisites: dedent`
- You should have an existing C# (.NET) project in a repository on GitHub.com. If you don't have a project, you can try this tutorial with the following example: https://github.com/2percentsilk/python-quickstart.
- Codespaces must be enabled for your organization. For more information, see "[Enabling Codespaces for your organization](/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization)."
`,
contentBlocks: [
{
codeBlock: {
id: '0',
},
type: 'default',
title: 'Step 1: Open your project in a codespace',
content: dedent`
1. Under the repository name, use the **Code** drop-down menu, and in the **Codespaces** tab, click **New codespace**.
![New codespace button](/assets/images/help/codespaces/new-codespace-button.png)
If you don’t see this option, Codespaces isn't available for your project. See [Access to Codespaces](/codespaces/developing-in-codespaces/creating-a-codespace#access-to-codespaces) for more information.
When you create a codespace, your project is created on a remote VM that is dedicated to you. By default, the container for your codespace has many languages and runtimes including .NET. It also includes a common set of tools like git, wget, rsync, openssh, and nano.
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.
Codespaces uses a file called \`devcontainer.json\` to store configurations. On launch 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)."
`,
},
{
codeBlock: {
id: '0',
},
type: 'default',
title: 'Step 2: Add a dev container to your codespace from a template',
content: dedent`
The default codespaces container comes with the latest .NET version and 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 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 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)".
1. Access the Command Palette (\`Shift + Command + P\` / \`Ctrl + Shift + P\`), then start typing "dev container". Select **Codespaces: Add Development Container Configuration Files...**.
![Codespaces: Add Development Container Configuration Files... in the command palette](/assets/images/help/codespaces/add-prebuilt-container-command.png)
2. For this example, click **C# (.NET)**. If you need additional features you can select any container that’s specific to C# (.NET) or a combination of tools such as C# (.NET) and MS SQL.
![Select C# (.NET) option from the list](/assets/images/help/codespaces/add-dotnet-prebuilt-container.png)
3. Click the recommended version of .NET.
![.NET version selection](/assets/images/help/codespaces/add-dotnet-version.png)
4. Accept the default option to add Node.js to your customization.
![Add Node.js selection](/assets/images/help/codespaces/dotnet-options.png)
5. Select any additional features to install and click **OK**.
6. Access the command palette (\`Shift + Command + P\`/ \`Ctrl + Shift + P\`), then start typing "rebuild". Select **Codespaces: Rebuild Container**.
![Rebuild container option](/assets/images/help/codespaces/codespaces-rebuild.png)
`,
},
{
codeBlock: {
id: '0',
},
type: 'sub-section',
title: 'Anatomy of your dev container',
content: dedent`
Adding the C# (.NET) dev container template adds a \`.devcontainer\` folder to the root of your project's repository with the following files:
- \`devcontainer.json\`
- Dockerfile
The newly added \`devcontainer.json\` file defines a few properties that are described below.
`,
},
{
type: 'sub-section-2',
codeBlock: {
id: '0',
highlight: 2,
},
content: dedent`
**\`name\`** - You can name your dev container anything, this is just the default.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: [3, 13],
},
content: dedent`
**\`build\`** - The build properties.
- **\`dockerfil\`e** - In the build object, dockerfile is a reference to the Dockerfile that was also added from the template.
- **\`args\`**
- **\`VARIANT\`**: This file only contains one build argument, which is the .NET Core version that we want to use.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: [16, 18],
},
content: dedent`
**\`settings\`** - These are Visual Studio Code settings that you can set.
- **\`terminal.integrated.shell.linux\`** - While bash is the default here, you could use other terminal shells by modifying this.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: [20, 23],
},
content: dedent`
**\`extensions\`** - These are extensions included by default.
- **\`ms-dotnettools.csharp\`** - The Microsoft C# extension provides rich support for developing in C#, including features such as IntelliSense, linting, debugging, code navigation, code formatting, refactoring, variable explorer, test explorer, and more.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: 26,
},
content: dedent`
**\`forwardPorts\`** - Any ports listed here will be forwarded automatically.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: 29,
},
content: dedent`
**\`postCreateCommand\`** - If you want to run anything after you land in your codespace that’s not defined in the Dockerfile, like \`dotnet restore\`, you can do that here.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: 32,
},
content: dedent`
**\`remoteUser\`** - By default, you’re running as the vscode user, but you can optionally set this to root.
`,
},
{
codeBlock: {
id: '1',
},
type: 'sub-section',
title: 'Dockerfile',
content: dedent`
You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our Dockerfile.
`,
},
{
codeBlock: {
id: '0',
highlight: [21, 29],
},
type: 'default',
title: 'Step 3: Modify your devcontainer.json file',
content: dedent`
With your dev container added and a basic understanding of what everything does, you can now make changes to configure it for your environment. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.
1. In the Explorer, expand the \`.devcontainer\` folder and select the \`devcontainer.json\` file from the tree to open it.
![devcontainer.json file in the Explorer](/assets/images/help/codespaces/devcontainers-options.png)
2. Update your the \`extensions\` list in your \`devcontainer.json\` file to add a few extensions that are useful when working with your project.
\`\`\`json{:copy}
"extensions": [
"ms-dotnettools.csharp",
"streetsidesoftware.code-spell-checker",
],
\`\`\`
3. Uncomment the \`postCreateCommand\` to restore dependencies as part of the codespace setup process.
\`\`\`json{:copy}
// Use 'postCreateCommand' to run commands after the container is created.
"postCreateCommand": "dotnet restore",
\`\`\`
4. Access the command palette (\`Shift + Command + P\`/ \`Ctrl + Shift + P\`), then start typing "rebuild". Select **Codespaces: Rebuild Container**.
![Rebuild container option](/assets/images/help/codespaces/codespaces-rebuild.png)
Rebuilding inside your codespace ensures your changes work as expected before you commit the changes to the repository. If something does result in a failure, you’ll be placed in a codespace with a recovery container that you can rebuild from to keep adjusting your container.
5. Check your changes were successfully applied by verifying the "Code Spell Checker" extension was installed.
![Extensions list](/assets/images/help/codespaces/dotnet-extensions.png)
`,
},
{
codeBlock: {
id: '0',
},
type: 'default',
title: 'Step 4: Run your application',
content: dedent`
In the previous section, you used the \`postCreateCommand\` to install a set of packages via the \`dotnet restore\` command. With our dependencies now installed, we can run our application.
1. Run your application by pressing \`F5\` or entering \`dotnet watch run\` in your terminal.
2. When your project starts, you should see a message in the bottom right corner with a prompt to connect to the port your project uses.
![Port forwarding toast](/assets/images/help/codespaces/python-port-forwarding.png)
`,
},
{
codeBlock: {
id: '0',
},
type: 'default',
title: 'Step 5: Commit your changes',
content: dedent`
Once you've made changes to your codespace, either new code or configuration changes, you'll want to commit your changes. Committing changes to your repository ensures that anyone else who creates a codespace from this repository has the same configuration. This also means that any customization you do, such as adding Visual Studio Code extensions, will appear for all users.
For information, see "[Using source control in your codespace](/codespaces/developing-in-codespaces/using-source-control-in-your-codespace#committing-your-changes)."
`,
},
],
codeBlocks: {
'0': {
fileName: '.devcontainer/devcontainer.json',
language: 'json',
code: dedent`
{
"name": "C# (.NET)",
"build": {
"dockerfile": "Dockerfile",
"args": {
// Update 'VARIANT' to pick a .NET Core version: 2.1, 3.1, 5.0
"VARIANT": "5.0",
// Options
"INSTALL_NODE": "true",
"NODE_VERSION": "lts/*",
"INSTALL_AZURE_CLI": "false"
}
},
// Set *default* container specific settings.json values on container create.
"settings": {
"terminal.integrated.shell.linux": "/bin/bash"
},
// Add the IDs of extensions you want installed when the container is created.
"extensions": [
"ms-dotnettools.csharp"
],
// Use 'forwardPorts' to make a list of ports inside the container available locally.
// "forwardPorts": [5000, 5001],
// Use 'postCreateCommand' to run commands after the container is created.
// "postCreateCommand": "dotnet restore",
// Comment out connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
"remoteUser": "vscode"
}
`,
},
'1': {
fileName: '.devcontainer/Dockerfile',
language: 'bash',
code: dedent`
# [Choice] .NET version: 5.0, 3.1, 2.1
ARG VARIANT="5.0"
FROM mcr.microsoft.com/vscode/devcontainers/dotnetcore:0-\${VARIANT}
# [Option] Install Node.js
ARG INSTALL_NODE="true"
ARG NODE_VERSION="lts/*"
RUN if [ "\${INSTALL_NODE}" = "true" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install \${NODE_VERSION} 2>&1"; fi
# [Option] Install Azure CLI
ARG INSTALL_AZURE_CLI="false"
COPY library-scripts/azcli-debian.sh /tmp/library-scripts/
RUN if [ "$INSTALL_AZURE_CLI" = "true" ]; then bash /tmp/library-scripts/azcli-debian.sh; fi \
&& apt-get clean -y && rm -rf /var/lib/apt/lists/* /tmp/library-scripts
# [Optional] Uncomment this section to install additional OS packages.
# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
# && apt-get -y install --no-install-recommends <your-package-list-here>
# [Optional] Uncomment this line to install global node packages.
# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g <your-package-here>" 2>&1
`,
},
},
}
export default article

294
components/playground/content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces/java.tsx Normal file
View File

@@ -0,0 +1,294 @@
import dedent from 'ts-dedent'
import { PlaygroundArticleT } from 'components/playground/types'
const article: PlaygroundArticleT = {
title: 'Add a dev container to your project',
shortTitle: 'Add a dev container to your project',
topics: ['Codespaces', 'Developer', 'Organization', 'Java'],
type: 'tutorial',
slug: '/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces',
originalArticle:
'/codespaces/setting-up-your-project-for-codespaces/setting-up-your-java-project-for-codespaces',
codeLanguageId: 'java',
intro: dedent`
This guide shows you how to add a [dev container](/codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project) to define the Codespaces configuration for your **Java** project. For other project languages, click the language button to the right.
`,
prerequisites: dedent`
- You should have an existing Java project in a repository on GitHub.com. If you don't have a project, you can try this tutorial with the following example: https://github.com/microsoft/vscode-remote-try-java
- Codespaces must be enabled for your organization. For more information, see "[Enabling Codespaces for your organization](/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization)."
`,
contentBlocks: [
{
codeBlock: {
id: '0',
},
type: 'default',
title: 'Step 1: Open your project in a codespace',
content: dedent`
1. Under the repository name, use the **Code** drop-down menu, and in the **Codespaces** tab, click **New codespace**.
![New codespace button](/assets/images/help/codespaces/new-codespace-button.png)
If you don’t see this option, Codespaces isn't available for your project. See [Access to Codespaces](/codespaces/developing-in-codespaces/creating-a-codespace#access-to-codespaces) for more information.
When you create a codespace, your project is created on a remote VM that is dedicated to you. By default, the container for your codespace has many languages and runtimes including Java, nvm, npm, and yarn. It also includes a common set of tools like git, wget, rsync, openssh, and nano.
Codespaces uses a file called \`devcontainer.json\` to store configurations. On launch 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)."
`,
},
{
codeBlock: {
id: '0',
},
type: 'default',
title: 'Step 2: Add a dev container to your codespace from a template',
content: dedent`
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 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 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)".
1. Access the Command Palette (\`Shift + Command + P\` / \`Ctrl + Shift + P\`), then start typing "dev container". Select **Codespaces: Add Development Container Configuration Files...**.
!["Codespaces: Add Development Container Configuration Files..." in the command palette](/assets/images/help/codespaces/add-prebuilt-container-command.png)
2. For this example, click **Java**. In practice, you could select any container that’s specific to Java or a combination of tools such as Java and Azure Functions.
![Select Java option from the list](/assets/images/help/codespaces/add-java-prebuilt-container.png)
3. Click the recommended version of Java.
![Java version selection](/assets/images/help/codespaces/add-java-version.png)
4. Select any additional features to install and click **OK**.
5. Access the command palette (\`Shift + Command + P\`/ \`Ctrl + Shift + P\`), then start typing "rebuild". Select **Codespaces: Rebuild Container**.
![Rebuild container option](/assets/images/help/codespaces/codespaces-rebuild.png)
`,
},
{
codeBlock: {
id: '0',
},
type: 'sub-section',
title: 'Anatomy of your dev container',
content: dedent`
Adding the Java dev container template adds a .devcontainer folder to the root of your project's repository with the following files:
- \`devcontainer.json\`
- Dockerfile
The newly added \`devcontainer.json\` file defines a few properties that are described below.
`,
},
{
type: 'sub-section-2',
codeBlock: {
id: '0',
highlight: 4,
},
content: dedent`
**\`name\`** - You can name your dev container anything, this is just the default.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: [5, 16],
},
content: dedent`
**\`build\`** - The build properties.
- **\`dockerfile\`** - In the build object, dockerfile is a reference to the Dockerfile that was also added from the template.
- **\`args\`**
- **\`VARIANT\`**: This file only contains one build argument, which is the Java version that is passed into the Dockerfile.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: [19, 23],
},
content: dedent`
**\`settings\`** - These are Visual Studio Code settings that you can set.
- **\`terminal.integrated.shell.linux\`** - While bash is the default here, you could use other terminal shells by modifying this.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: [26, 28],
},
content: dedent`
**\`extensions\`** - These are extensions included by default.
- **\`vscjava.vscode-java-pack\`** - The Java Extension Pack provides popular extensions for Java development to get you started.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: 31,
},
content: dedent`
**\`forwardPorts\`** - Any ports listed here will be forwarded automatically.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: 34,
},
content: dedent`
**\`postCreateCommand\`** - If you want to run anything after you land in your codespace that’s not defined in the Dockerfile, you can do that here.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: 37,
},
content: dedent`
**\`remoteUser\`** - By default, you’re running as the vscode user, but you can optionally set this to root.
`,
},
{
codeBlock: {
id: '1',
},
type: 'sub-section',
title: 'Dockerfile',
content: dedent`
You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our Dockerfile.
`,
},
{
codeBlock: {
id: '0',
highlight: [30, 34],
},
type: 'default',
title: 'Step 3: Modify your devcontainer.json file',
content: dedent`
With your dev container added and a basic understanding of what everything does, you can now make changes to configure it for your environment. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.
1. In the Explorer, expand the \`.devcontainer\` folder and select the \`devcontainer.json\` file from the tree to open it.
![devcontainer.json file in the Explorer](/assets/images/help/codespaces/devcontainers-options.png)
2. Add the following lines to your \`devcontainer.json\` file after \`extensions\`.
\`\`\`json{:copy}
"postCreateCommand": "java -version",
"forwardPorts": [4000],
\`\`\`
For more information on \`devcontainer.json\` properties, see the [devcontainer.json reference](https://code.visualstudio.com/docs/remote/devcontainerjson-reference) on the Visual Studio Code docs.
4. Access the command palette (\`Shift + Command + P\`/ \`Ctrl + Shift + P\`), then start typing "rebuild". Select **Codespaces: Rebuild Container**.
![Rebuild container option](/assets/images/help/codespaces/codespaces-rebuild.png)
Rebuilding inside your codespace ensures your changes work as expected before you commit the changes to the repository. If something does result in a failure, you’ll be placed in a codespace with a recovery container that you can rebuild from to keep adjusting your container.
`,
},
{
codeBlock: {
id: '0',
},
type: 'default',
title: 'Step 4: Run your application',
content: dedent`
In the previous section, you used the \`postCreateCommand\` to install a set of packages via npm. You can now use this to run our application with npm.
1. Run your application by pressing \`F5\`.
2. When your project starts, you should see a message in the bottom right corner with a prompt to connect to the port your project uses.
![Port forwarding toast](/assets/images/help/codespaces/codespaces-port-toast.png)
`,
},
{
codeBlock: {
id: '0',
},
type: 'default',
title: 'Step 5: Commit your changes',
content: dedent`
Once you've made changes to your codespace, either new code or configuration changes, you'll want to commit your changes. Committing changes to your repository ensures that anyone else who creates a codespace from this repository has the same configuration. This also means that any customization you do, such as adding Visual Studio Code extensions, will appear for all users.
For information, see "[Using source control in your codespace](/codespaces/developing-in-codespaces/using-source-control-in-your-codespace#committing-your-changes)."
`,
},
],
codeBlocks: {
'0': {
fileName: '.devcontainer/devcontainer.json',
language: 'json',
code: dedent`
// For format details, see https://aka.ms/vscode-remote/devcontainer.json or this file's README at:
// https://github.com/microsoft/vscode-dev-containers/tree/v0.159.0/containers/java
{
"name": "Java",
"build": {
"dockerfile": "Dockerfile",
"args": {
// Update the VARIANT arg to pick a Java version: 11, 14
"VARIANT": "11",
// Options
"INSTALL_MAVEN": "true",
"INSTALL_GRADLE": "false",
"INSTALL_NODE": "false",
"NODE_VERSION": "lts/*"
}
},
// Set *default* container specific settings.json values on container create.
"settings": {
"terminal.integrated.shell.linux": "/bin/bash",
"java.home": "/docker-java-home",
"maven.executable.path": "/usr/local/sdkman/candidates/maven/current/bin/mvn"
},
// Add the IDs of extensions you want installed when the container is created.
"extensions": [
"vscjava.vscode-java-pack"
],
// Use 'forwardPorts' to make a list of ports inside the container available locally.
// "forwardPorts": [],
// Use 'postCreateCommand' to run commands after the container is created.
// "postCreateCommand": "java -version",
// Uncomment to connect as a non-root user. See https://aka.ms/vscode-remote/containers/non-root.
"remoteUser": "vscode"
}
`,
},
'1': {
fileName: '.devcontainer/Dockerfile',
language: 'bash',
code: dedent`
# See here for image contents: https://github.com/microsoft/vscode-dev-containers/tree/v0.159.0/containers/java/.devcontainer/base.Dockerfile
ARG VARIANT="14"
FROM mcr.microsoft.com/vscode/devcontainers/java:0-\${VARIANT}
# [Optional] Install Maven or Gradle
ARG INSTALL_MAVEN="false"
ARG MAVEN_VERSION=3.6.3
ARG INSTALL_GRADLE="false"
ARG GRADLE_VERSION=5.4.1
RUN if [ "\${INSTALL_MAVEN}" = "true" ]; then su vscode -c "source /usr/local/sdkman/bin/sdkman-init.sh && sdk install maven \"\${MAVEN_VERSION}\""; fi \
&& if [ "\${INSTALL_GRADLE}" = "true" ]; then su vscode -c "source /usr/local/sdkman/bin/sdkman-init.sh && sdk install gradle \"\${GRADLE_VERSION}\""; fi
# [Optional] Install a version of Node.js using nvm for front end dev
ARG INSTALL_NODE="true"
ARG NODE_VERSION="lts/*"
RUN if [ "\${INSTALL_NODE}" = "true" ]; then su vscode -c "source /usr/local/share/nvm/nvm.sh && nvm install \${NODE_VERSION} 2>&1"; fi
# [Optional] Uncomment this section to install additional OS packages.
# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
# && apt-get -y install --no-install-recommends <your-package-list-here>
# [Optional] Uncomment this line to install global node packages.
# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g <your-package-here>" 2>&1
`,
},
},
}
export default article

278
components/playground/content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces/nodejs.tsx Normal file
View File

@@ -0,0 +1,278 @@
import dedent from 'ts-dedent'
import { PlaygroundArticleT } from 'components/playground/types'
const article: PlaygroundArticleT = {
title: 'Add a dev container to your project',
shortTitle: 'Node.js Codespaces',
topics: ['Codespaces', 'Developer', 'Organization', 'Node', 'JavaScript'],
type: 'tutorial',
slug: '/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces',
originalArticle:
'/codespaces/setting-up-your-project-for-codespaces/setting-up-your-nodejs-project-for-codespaces',
codeLanguageId: 'nodejs',
intro: dedent`
This guide shows you how to add a [dev container](/codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project) to define the Codespaces configuration for your **JavaScript**, **Node.js**, or **TypeScript** project. For other project languages, click the language button to the right.
`,
prerequisites: dedent`
- You should have an existing JavaScript, Node.js, or TypeScript project in a repository on GitHub.com. If you don't have a project, you can try this tutorial with the following example: https://github.com/microsoft/vscode-remote-try-node
- Codespaces must be enabled for your organization. For more information, see "[Enabling Codespaces for your organization](/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization)."
`,
contentBlocks: [
{
codeBlock: {
id: '0',
},
type: 'default',
title: 'Step 1: Open your project in a codespace',
content: dedent`
1. Under the repository name, use the **Code** drop-down menu, and in the **Codespaces** tab, click **New codespace**.
![New codespace button](/assets/images/help/codespaces/new-codespace-button.png)
If you don’t see this option, Codespaces isn't available for your project. See [Access to Codespaces](/codespaces/developing-in-codespaces/creating-a-codespace#access-to-codespaces) for more information.
When you create a codespace, your project is created on a remote VM that is dedicated to you. By default, the container for your codespace has many languages and runtimes including Node.js, JavaScript, Typescript, nvm, npm, and yarn. It also includes a common set of tools like git, wget, rsync, openssh, and nano.
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.
Codespaces uses a file called \`devcontainer.json\` to store configurations. On launch, 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)."
`,
},
{
codeBlock: {
id: '0',
},
type: 'default',
title: 'Step 2: Add a dev container to your codespace from a template',
content: dedent`
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 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 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)".
1. Access the Command Palette (\`Shift + Command + P\` / \`Ctrl + Shift + P\`), then start typing "dev container". Select **Codespaces: Add Development Container Configuration Files...**.
!["Codespaces: Add Development Container Configuration Files..." in the command palette](/assets/images/help/codespaces/add-prebuilt-container-command.png)
2. 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.
![Select Node option from the list](/assets/images/help/codespaces/add-node-prebuilt-container.png)
3. Click the recommended version of Node.js.
![Node.js version selection](/assets/images/help/codespaces/add-node-version.png)
4. Select any additional features to install and click **OK**.
5. Access the command palette (\`Shift + Command + P\`/ \`Ctrl + Shift + P\`), then start typing "rebuild". Select **Codespaces: Rebuild Container**.
![Rebuild container option](/assets/images/help/codespaces/codespaces-rebuild.png)
`,
},
{
codeBlock: {
id: '0',
},
type: 'sub-section',
title: 'Anatomy of your dev container',
content: dedent`
Adding the Node.js dev container template adds a \`.devcontainer\` folder to the root of your project's repository with the following files:
- \`devcontainer.json\`
- Dockerfile
The newly added \`devcontainer.json\` file defines a few properties that are described below.
`,
},
{
type: 'sub-section-2',
codeBlock: {
id: '0',
highlight: 4,
},
content: dedent`
**\`name\`** - You can name your dev container anything, this is just the default.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: [5, 9],
},
content: dedent`
**\`build\`** - The build properties.
- **\`dockerfile\`** - In the build object, dockerfile is a reference to the Dockerfile that was also added from the template.
- **\`args\`**
- **\`VARIANT\`**: This file only contains one build argument, which is the node variant we want to use that is passed into the Dockerfile.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: [12, 14],
},
content: dedent`
**\`settings\`** - These are Visual Studio Code settings that you can set.
- **\`terminal.integrated.shell.linux\`** - While bash is the default here, you could use other terminal shells by modifying this.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: [17, 19],
},
content: dedent`
**\`extensions\`** - These are extensions included by default.
- **\`dbaeumer.vscode-eslint\`** - ES lint is a great extension for linting, but for JavaScript there are a number of great Marketplace extensions you could also include.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: 22,
},
content: dedent`
**\`forwardPorts\`** - Any ports listed here will be forwarded automatically.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: 25,
},
content: dedent`
**\`postCreateCommand\`** - If you want to run anything after you land in your codespace that’s not defined in the Dockerfile, you can do that here.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: 28,
},
content: dedent`
**\`remoteUser\`** - By default, you’re running as the vscode user, but you can optionally set this to root.
`,
},
{
codeBlock: {
id: '1',
},
type: 'sub-section',
title: 'Dockerfile',
content: dedent`
You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our Dockerfile.
`,
},
{
codeBlock: {
id: '0',
highlight: [21, 25],
},
type: 'default',
title: 'Step 3: Modify your devcontainer.json file',
content: dedent`
With your dev container added and a basic understanding of what everything does, you can now make changes to configure it for your environment. In this example, you'll add properties to install npm when your codespace launches and make a list of ports inside the container available locally.
1. In the Explorer, select the \`devcontainer.json\` file from the tree to open it. You might have to expand the \`.devcontainer\` folder to see it.
![devcontainer.json file in the Explorer](/assets/images/help/codespaces/devcontainers-options.png)
2. Add the following lines to your \`devcontainer.json\` file after \`extensions\`:
\`\`\`js{:copy}
"postCreateCommand": "npm install",
"forwardPorts": [4000],
\`\`\`
For more information on \`devcontainer.json\` properties, see the [devcontainer.json reference](https://code.visualstudio.com/docs/remote/devcontainerjson-reference) in the Visual Studio Code docs.
1. Access the command palette (\`Shift + Command + P\`/ \`Ctrl + Shift + P\`), then start typing "rebuild". Select **Codespaces: Rebuild Container**.
![Rebuild container option](/assets/images/help/codespaces/codespaces-rebuild.png)
Rebuilding inside your codespace ensures your changes work as expected before you commit the changes to the repository. If something does result in a failure, you’ll be placed in a codespace with a recovery container that you can rebuild from to keep adjusting your container.
`,
},
{
codeBlock: {
id: '0',
},
type: 'default',
title: 'Step 4: Run your application',
content: dedent`
In the previous section, you used the \`postCreateCommand\` to installing a set of packages via npm. You can now use this to run our application with npm.
1. Run your start command in the terminal with \`npm start\`.
![npm start in terminal](/assets/images/help/codespaces/codespaces-npmstart.png)
2. When your project starts, you should see a message in the bottom right corner with a prompt to connect to the port your project uses.
![Port forwarding toast](/assets/images/help/codespaces/codespaces-port-toast.png)
`,
},
{
codeBlock: {
id: '0',
},
type: 'default',
title: 'Step 5: Commit your changes',
content: dedent`
Once you've made changes to your codespace, either new code or configuration changes, you'll want to commit your changes. Committing changes to your repository ensures that anyone else who creates a codespace from this repository has the same configuration. This also means that any customization you do, such as adding Visual Studio Code extensions, will appear for all users.
For information, see "[Using source control in your codespace](/codespaces/developing-in-codespaces/using-source-control-in-your-codespace#committing-your-changes)."
`,
},
],
codeBlocks: {
'0': {
fileName: '.devcontainer/devcontainer.json',
language: 'json',
code: dedent`
// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
// https://github.com/microsoft/vscode-dev-containers/tree/v0.162.0/containers/javascript-node
{
"name": "Node.js",
"build": {
"dockerfile": "Dockerfile",
// Update 'VARIANT' to pick a Node version: 10, 12, 14
"args": { "VARIANT": "14" }
},
// Set *default* container specific settings.json values on container create.
"settings": {
"terminal.integrated.shell.linux": "/bin/bash"
},
// Add the IDs of extensions you want installed when the container is created.
"extensions": [
"dbaeumer.vscode-eslint"
],
// Use 'forwardPorts' to make a list of ports inside the container available locally.
// "forwardPorts": [],
// Use 'postCreateCommand' to run commands after the container is created.
// "postCreateCommand": "yarn install",
// Comment out connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
"remoteUser": "node"
}
`,
},
'1': {
fileName: '.devcontainer/Dockerfile',
language: 'bash',
code: dedent`
# [Choice] Node.js version: 14, 12, 10
ARG VARIANT="14-buster"
FROM mcr.microsoft.com/vscode/devcontainers/javascript-node:0-\${VARIANT}
# [Optional] Uncomment this section to install additional OS packages.
# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive && apt-get -y install --no-install-recommends <your-package-list-here>
# [Optional] Uncomment if you want to install an additional version of node using nvm
# ARG EXTRA_NODE_VERSION=10
# RUN su node -c "source /usr/local/share/nvm/nvm.sh && nvm install \${EXTRA_NODE_VERSION}"
# [Optional] Uncomment if you want to install more global node modules
# RUN su node -c "npm install -g <your-package-list-here>"
`,
},
},
}
export default article

318
components/playground/content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces/python.tsx Normal file
View File

@@ -0,0 +1,318 @@
import dedent from 'ts-dedent'
import { PlaygroundArticleT } from 'components/playground/types'
const article: PlaygroundArticleT = {
title: 'Add a dev container to your repository',
shortTitle: 'Python Codespaces',
topics: ['Codespaces', 'Developer', 'Organization', 'Python'],
type: 'tutorial',
slug: '/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces',
originalArticle:
'/codespaces/setting-up-your-project-for-codespaces/setting-up-your-python-project-for-codespaces',
codeLanguageId: 'py',
intro: dedent`
This guide shows you how to add a [dev container](/codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project) to define the Codespaces configuration for your **Python** project. For other project languages, click the language button to the right.
`,
prerequisites: dedent`
- You should have an existing Python project in a repository on GitHub.com. If you don't have a project, you can try this tutorial with the following example: https://github.com/2percentsilk/python-quickstart.
- Codespaces must be enabled for your organization. For more information, see "[Enabling Codespaces for your organization](/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization)."
`,
contentBlocks: [
{
codeBlock: {
id: '0',
},
type: 'default',
title: 'Step 1: Open your project in a codespace',
content: dedent`
1. Under the repository name, use the **Code** drop-down menu, and in the **Codespaces** tab, click **New codespace**.
![New codespace button](/assets/images/help/codespaces/new-codespace-button.png)
If you don’t see this option, Codespaces isn't available for your project. See [Access to Codespaces](/codespaces/developing-in-codespaces/creating-a-codespace#access-to-codespaces) for more information.
When you create a codespace, your project is created on a remote VM that is dedicated to you. By default, the container for your codespace has many languages and runtimes including Python, pip, and Miniconda. It also includes a common set of tools like git, wget, rsync, openssh, and nano.
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.
Codespaces uses a file called \`devcontainer.json\` to store configurations. On launch 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)."
`,
},
{
codeBlock: {
id: '0',
},
type: 'default',
title: 'Step 2: Add a dev container to your codespace from a template',
content: dedent`
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 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 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)".
1. Access the Command Palette (\`Shift + Command + P\` / \`Ctrl + Shift + P\`), then start typing "dev container". Select **Codespaces: Add Development Container Configuration Files...**.
!["Codespaces: Add Development Container Configuration Files..." in the command palette](/assets/images/help/codespaces/add-prebuilt-container-command.png)
2. For this example, click **Python 3**. If you need additional features you can select any container that’s specific to Python or a combination of tools such as Python 3 and PostgreSQL.
![Select Python option from the list](/assets/images/help/codespaces/add-python-prebuilt-container.png)
3. Click the recommended version of Python.
![Python version selection](/assets/images/help/codespaces/add-python-version.png)
4. Accept the default option to add Node.js to your customization.
![Add Node.js selection](/assets/images/help/codespaces/add-nodejs-selection.png)
5. Select any additional features to install and click **OK**.
6. Access the command palette (\`Shift + Command + P\`/ \`Ctrl + Shift + P\`), then start typing "rebuild". Select **Codespaces: Rebuild Container**.
![Rebuild container option](/assets/images/help/codespaces/codespaces-rebuild.png)
`,
},
{
codeBlock: {
id: '0',
},
type: 'sub-section',
title: 'Anatomy of your dev container',
content: dedent`
Adding the Python dev container template adds a .devcontainer folder to the root of your project's repository with the following files:
- \`devcontainer.json\`
- Dockerfile
The newly added \`devcontainer.json\` file defines a few properties that are described below.
`,
},
{
type: 'sub-section-2',
codeBlock: {
id: '0',
highlight: 2,
},
content: dedent`
**\`name\`** - You can name your dev container anything, this is just the default.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: [3, 12],
},
content: dedent`
**\`build\`** - The build properties.
- **\`dockerfile\`** - In the build object, dockerfile is a reference to the Dockerfile that was also added from the template.
- **\`args\`**
- **\`VARIANT\`**: This is the node variant we want to use that is passed into the Dockerfile.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: [16, 30],
},
content: dedent`
**\`settings\`** - These are Visual Studio Code settings that you can set.
- **\`terminal.integrated.shell.linux\`** - While bash is the default here, you could use other terminal shells by modifying this.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: [33, 35],
},
content: dedent`
**\`extensions\`** - These are extensions included by default.
- **\`ms-python.python\`** - The Microsoft Python extension provides rich support for the Python language (for all actively supported versions of the language: >=3.6), including features such as IntelliSense, linting, debugging, code navigation, code formatting, refactoring, variable explorer, test explorer, and more.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: 38,
},
content: dedent`
**\`forwardPorts\`** - Any ports listed here will be forwarded automatically.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: 41,
},
content: dedent`
**\`postCreateCommand\`** - If you want to run anything after you land in your codespace that’s not defined in the Dockerfile, like pip3 install -r requirements, you can do that here.
`,
},
{
type: 'sub-section',
codeBlock: {
id: '0',
highlight: 44,
},
content: dedent`
**\`remoteUser\`** - By default, you’re running as the vscode user, but you can optionally set this to root.
`,
},
{
codeBlock: {
id: '1',
},
type: 'sub-section',
title: 'Dockerfile',
content: dedent`
You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our Dockerfile.
`,
},
{
codeBlock: {
id: '0',
highlight: [32, 41],
},
type: 'default',
title: 'Step 3: Modify your devcontainer.json file',
content: dedent`
With your dev container added and a basic understanding of what everything does, you can now make changes to configure it for your environment. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.
1. In the Explorer, expand the \`.devcontainer\` folder and select the \`devcontainer.json\` file from the tree to open it.
![devcontainer.json file in the Explorer](/assets/images/help/codespaces/devcontainers-options.png)
2. Update the extensions list in your \`devcontainer.json\` file to add a few extensions that are useful when working with your project.
\`\`\`json{:copy}
"extensions": [
"ms-python.python",
"cstrap.flask-snippets",
"streetsidesoftware.code-spell-checker",
],
\`\`\`
3. Uncomment the \`postCreateCommand\` to auto-install requirements as part of the codespaces setup process.
\`\`\`json{:copy}
// Use 'postCreateCommand' to run commands after the container is created.
"postCreateCommand": "pip3 install --user -r requirements.txt",
\`\`\`
4. Access the command palette (\`Shift + Command + P\`/ \`Ctrl + Shift + P\`), then start typing "rebuild". Select **Codespaces: Rebuild Container**.
![Rebuild container option](/assets/images/help/codespaces/codespaces-rebuild.png)
Rebuilding inside your codespace ensures your changes work as expected before you commit the changes to the repository. If something does result in a failure, you’ll be placed in a codespace with a recovery container that you can rebuild from to keep adjusting your container.
5. Check your changes were successfully applied by verifying the Code Spell Checker and Flask Snippet extensions were installed.
![Extensions list](/assets/images/help/codespaces/python-extensions.png)
`,
},
{
codeBlock: {
id: '0',
},
type: 'default',
title: 'Step 4: Run your application',
content: dedent`
In the previous section, you used the \`postCreateCommand\` to install a set of packages with pip3. With your dependencies now installed, you can run your application.
1. Run your application by pressing F5 or entering \`python -m flask run\` in the codespace terminal.
2. When your project starts, you should see a message in the bottom right corner with a prompt to connect to the port your project uses.
![Port forwarding toast](/assets/images/help/codespaces/python-port-forwarding.png)
`,
},
{
codeBlock: {
id: '0',
},
type: 'default',
title: 'Step 5: Commit your changes',
content: dedent`
Once you've made changes to your codespace, either new code or configuration changes, you'll want to commit your changes. Committing changes to your repository ensures that anyone else who creates a codespace from this repository has the same configuration. This also means that any customization you do, such as adding Visual Studio Code extensions, will appear for all users.
For information, see "[Using source control in your codespace](/codespaces/developing-in-codespaces/using-source-control-in-your-codespace#committing-your-changes)."
`,
},
],
codeBlocks: {
'0': {
fileName: '.devcontainer/devcontainer.json',
language: 'json',
code: dedent`
{
"name": "Python 3",
"build": {
"dockerfile": "Dockerfile",
"context": "..",
"args": {
// Update 'VARIANT' to pick a Python version: 3, 3.6, 3.7, 3.8, 3.9
"VARIANT": "3",
// Options
"INSTALL_NODE": "true",
"NODE_VERSION": "lts/*"
}
},
// Set *default* container specific settings.json values on container create.
"settings": {
"terminal.integrated.shell.linux": "/bin/bash",
"python.pythonPath": "/usr/local/bin/python",
"python.linting.enabled": true,
"python.linting.pylintEnabled": true,
"python.formatting.autopep8Path": "/usr/local/py-utils/bin/autopep8",
"python.formatting.blackPath": "/usr/local/py-utils/bin/black",
"python.formatting.yapfPath": "/usr/local/py-utils/bin/yapf",
"python.linting.banditPath": "/usr/local/py-utils/bin/bandit",
"python.linting.flake8Path": "/usr/local/py-utils/bin/flake8",
"python.linting.mypyPath": "/usr/local/py-utils/bin/mypy",
"python.linting.pycodestylePath": "/usr/local/py-utils/bin/pycodestyle",
"python.linting.pydocstylePath": "/usr/local/py-utils/bin/pydocstyle",
"python.linting.pylintPath": "/usr/local/py-utils/bin/pylint"
},
// Add the IDs of extensions you want installed when the container is created.
"extensions": [
"ms-python.python",
],
// Use 'forwardPorts' to make a list of ports inside the container available locally.
// "forwardPorts": [],
// Use 'postCreateCommand' to run commands after the container is created.
// "postCreateCommand": "pip3 install --user -r requirements.txt",
// Comment out connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
"remoteUser": "vscode"
}
`,
},
'1': {
fileName: '.devcontainer/Dockerfile',
language: 'bash',
code: dedent`
# [Choice] Python version: 3, 3.9, 3.8, 3.7, 3.6
ARG VARIANT="3"
FROM mcr.microsoft.com/vscode/devcontainers/python:0-\${VARIANT}
# [Option] Install Node.js
ARG INSTALL_NODE="true"
ARG NODE_VERSION="lts/*"
RUN if [ "\${INSTALL_NODE}" = "true" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install \${NODE_VERSION} 2>&1"; fi
# [Optional] If your pip requirements rarely change, uncomment this section to add them to the image.
# COPY requirements.txt /tmp/pip-tmp/
# RUN pip3 --disable-pip-version-check --no-cache-dir install -r /tmp/pip-tmp/requirements.txt \
# && rm -rf /tmp/pip-tmp
# [Optional] Uncomment this section to install additional OS packages.
# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
# && apt-get -y install --no-install-recommends <your-package-list-here>
# [Optional] Uncomment this line to install global node packages.
# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g <your-package-here>" 2>&1
`,
},
},
}
export default article