Repository: open-telemetry/opentelemetry.io
Pull request #6738: Add devcontainer.json for local development using devcontainers
Author: login: avillela
Labels: name: CI/infra
description: Repo CI & infrastructure
name: lang:zh
name: lang:ja
name: lang:pt
name: lang:es
Created: 2025-04-22T19:26:00Z | Merged: 2025-04-30T21:55:43Z

Adding a Dev Container definition for this repo, so that others wishing to contribute to the OTel docs have the option of running it locally using the VSCode Dev Container plugin. I've updated the corresponding docs page as well. I've tested the dev container myself, as I used it when working on this PR. 😁


Diff:
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 000000000000..f91c948b6ce1
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,18 @@
+{
+  "name": "default",
+  "image": "mcr.microsoft.com/devcontainers/base:dev-bullseye",
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {}
+  },
+  "overrideFeatureInstallOrder": [],
+  "hostRequirements": {
+    "cpus": 4,
+    "memory": "16gb",
+    "storage": "16gb"
+  },
+  "remoteEnv": {
+    "PODMAN_USERNS": "keep-id"
+  },
+  "containerUser": "vscode",
+  "postStartCommand": ".devcontainer/post-start.sh"
+}
diff --git a/.devcontainer/post-start.sh b/.devcontainer/post-start.sh
new file mode 100755
index 000000000000..f152ff9dd0a6
--- /dev/null
+++ b/.devcontainer/post-start.sh
@@ -0,0 +1,4 @@
+#!/bin/bash
+
+nvm install
+npm install
diff --git a/content/en/docs/contributing/development.md b/content/en/docs/contributing/development.md
index 76e99809c2e1..8d4df615b5fa 100644
--- a/content/en/docs/contributing/development.md
+++ b/content/en/docs/contributing/development.md
@@ -28,6 +28,30 @@ Gitpod automatically installs the repo-specific packages for you.
 You're now ready to [build](#build), [serve](#serve) or make updates to the
 website files.
 
+## Development container setup
+
+{{% alert title="Note" %}}
+
+[Development (dev) containers](https://containers.dev/) are a standard. You can
+therefore you run the dev container for this repository using any tool
+supporting this standard, such as:
+
+- [GitHub Codespaces](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#about-dev-containers)
+- [DevPod](https://devpod.sh/docs/developing-in-workspaces/devcontainer-json)
+- [VSCode](https://code.visualstudio.com/docs/devcontainers/containers#_installation)
+
+{{% /alert %}}
+
+1.  [Fork][] and then [clone][] the website repository at
+    <{{% param github_repo %}}>.
+
+2.  Go to the repository directory.
+
+3.  Open up the project in your favorite Dev Container tool.
+
+You're now ready to [build](#build), [serve](#serve) or make updates to the
+website files.
+
 ## Local setup
 
 1.  [Fork][] and then [clone][] the website repository at
diff --git a/static/refcache.json b/static/refcache.json
index 64a31e921af3..8e46bd488332 100644
--- a/static/refcache.json
+++ b/static/refcache.json
@@ -539,10 +539,18 @@
     "StatusCode": 206,
     "LastSeen": "2025-02-01T06:58:05.02751-05:00"
   },
+  "https://code.visualstudio.com": {
+    "StatusCode": 206,
+    "LastSeen": "2025-04-22T19:19:29.392140654Z"
+  },
   "https://code.visualstudio.com/": {
     "StatusCode": 206,
     "LastSeen": "2025-01-30T16:59:55.593014-05:00"
   },
+  "https://code.visualstudio.com/docs/devcontainers/containers#_installation": {
+    "StatusCode": 206,
+    "LastSeen": "2025-04-22T19:19:32.045577138Z"
+  },
   "https://collectd.org/wiki/index.php/Binary_protocol": {
     "StatusCode": 206,
     "LastSeen": "2025-01-13T11:43:49.558162-05:00"
@@ -583,6 +591,10 @@
     "StatusCode": 206,
     "LastSeen": "2025-01-15T13:17:28.36005-05:00"
   },
+  "https://containers.dev/": {
+    "StatusCode": 206,
+    "LastSeen": "2025-04-22T19:19:25.586763282Z"
+  },
   "https://contribute.cncf.io/resources/project-services/audits/": {
     "StatusCode": 206,
     "LastSeen": "2025-01-04T17:06:30.360149-05:00"
@@ -927,6 +939,10 @@
     "StatusCode": 200,
     "LastSeen": "2025-01-30T16:59:50.483226-05:00"
   },
+  "https://devpod.sh/docs/developing-in-workspaces/devcontainer-json": {
+    "StatusCode": 206,
+    "LastSeen": "2025-04-30T15:20:21.96523571Z"
+  },
   "https://devstats.cncf.io/": {
     "StatusCode": 206,
     "LastSeen": "2025-01-06T11:33:39.730093-05:00"
@@ -1239,6 +1255,10 @@
     "StatusCode": 206,
     "LastSeen": "2025-02-01T07:20:41.337867-05:00"
   },
+  "https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#about-dev-containers": {
+    "StatusCode": 206,
+    "LastSeen": "2025-04-30T15:20:20.247498933Z"
+  },
   "https://docs.github.com/en/get-started/learning-about-github/github-glossary#pull-request": {
     "StatusCode": 200,
     "LastSeen": "2025-02-06T02:05:12.345Z"


Reviews:
user: login: svrnm
state: APPROVED
author_association: MEMBER
submitted_at: 2025-04-29T09:07:34Z
user: login: theletterf
state: APPROVED
author_association: MEMBER
submitted_at: 2025-04-29T09:28:32Z
user: login: chalin
body: /hold - so maintainers can finalize discussion

**Edit**: I've added some review comments, see below.
state: CHANGES_REQUESTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-29T11:44:25Z
user: login: chalin
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-29T11:54:09Z
user: login: avillela
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-30T15:17:02Z
user: login: chalin
body: There are some edits that I'd like to do to the docs addition, but I'll submit a followup PR. Let's merge this so that we can have the DevContainer config available. Will merge once all checks pass.
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-04-30T21:47:08Z

Review comments:
diff_hunk: @@ -0,0 +1,19 @@
+{
+  "name": "default",
+  "image": "mcr.microsoft.com/devcontainers/base:dev-bullseye",
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {}
+  },
+  "overrideFeatureInstallOrder": [],
+  "hostRequirements": {
+    "cpus": 4,
+    "memory": "16gb",
+    "storage": "16gb"
+  },
+  "remoteEnv": {
+    "PODMAN_USERNS": "keep-id"
+  },
+  "containerUser": "vscode",
+  // "postCreateCommand": ".devcontainer/post-create.sh",
path: .devcontainer/devcontainer.json
user: login: chalin
body: ```suggestion
```
created_at: 2025-04-29T11:47:26Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,4 @@
+#!/bin/bash
+
+nvm install
+npm install
path: .devcontainer/post-start.sh
user: login: chalin
body: ```suggestion
npm install

```
created_at: 2025-04-29T11:47:33Z
author_association: CONTRIBUTOR
diff_hunk: @@ -28,6 +28,40 @@ Gitpod automatically installs the repo-specific packages for you.
 You're now ready to [build](#build), [serve](#serve) or make updates to the
 website files.
 
+## Local development container setup
path: content/en/docs/contributing/development.md
user: login: chalin
body: I'd suggest that we move this to after the "Local setup" section, which is IDE independent.

```suggestion
## Local setup for DevContainers + VSCode
```
created_at: 2025-04-29T11:51:05Z
author_association: CONTRIBUTOR
diff_hunk: @@ -28,6 +28,40 @@ Gitpod automatically installs the repo-specific packages for you.
 You're now ready to [build](#build), [serve](#serve) or make updates to the
 website files.
 
+## Local development container setup
path: content/en/docs/contributing/development.md
user: login: chalin
body: I understand that using VSCode is simpler, but can one use other IDEs or work from the command line? If so, could we separate those instructions?
created_at: 2025-04-29T11:53:55Z
author_association: CONTRIBUTOR
diff_hunk: @@ -28,6 +28,40 @@ Gitpod automatically installs the repo-specific packages for you.
 You're now ready to [build](#build), [serve](#serve) or make updates to the
 website files.
 
+## Local development container setup
path: content/en/docs/contributing/development.md
user: login: avillela
body: Let me update the wording for this section, since Dev Containers can be used with GH Code Spaces, VSCode, and GitPod.
created_at: 2025-04-30T15:17:02Z
author_association: CONTRIBUTOR

PR comments:
user: login: svrnm
created_at: 2025-04-29T09:08:06Z
body: lgtm overall. Since it does not impact any other existing instructions or configurations I would be fine with merging it.
author_association: MEMBER
user: login: chalin
created_at: 2025-04-29T11:58:27Z
body: Could this DevContainer setup also be usable from a cloud IDE?
author_association: CONTRIBUTOR
user: login: chalin
created_at: 2025-04-29T12:01:34Z
body: A few more questions :)

- [ ] Who is going to champion updates to this DevContainer support?
- [ ] Shall we indicate that this support is experimental, and provided on a best effort basis?

author_association: CONTRIBUTOR
user: login: chalin
created_at: 2025-04-29T12:05:07Z
body: /off hold - once the comments are addressed. 👍🏻 
author_association: CONTRIBUTOR
user: login: avillela
created_at: 2025-04-30T14:51:21Z
body: > Could this DevContainer setup also be usable from a cloud IDE?

@chalin Yes. DevContainer is a standard, so this also works in GitHub Codespaces and DevPod. I've noted that in the docs page as well.
author_association: CONTRIBUTOR
user: login: avillela
created_at: 2025-04-30T15:42:16Z
body: > A few more questions :)
> 
> * [ ]  Who is going to champion updates to this DevContainer support?
> * [ ]  Shall we indicate that this support is experimental, and provided on a best effort basis?

@chalin The base dev container image includes a node.js add-on and then just the init commands for bootstrapping the environment. I don't believe that the base setup for the repo has changed, so I don't expect the dev container definition to change much (or at all).
author_association: CONTRIBUTOR
user: login: avillela
created_at: 2025-04-30T15:47:23Z
body: I ran `npm run test-and-fix` and it added a bunch of updates to this PR. 🫠
author_association: CONTRIBUTOR
user: login: chalin
created_at: 2025-04-30T19:35:43Z
body: > I ran `npm run test-and-fix` and it added a bunch of updates to this PR. 🫠

Right. Let's wait for the following to land first:

- #6788
author_association: CONTRIBUTOR
user: login: chalin
created_at: 2025-04-30T19:41:36Z
body: @avillela - Now that #6788 has been merged, please rebase this PR and drop changes to non-`en` locale pages. Thanks!
author_association: CONTRIBUTOR
user: login: chalin
created_at: 2025-05-01T00:09:12Z
body: See #6791 for followup edits, thanks!
author_association: CONTRIBUTOR