Skip to content

About

developer environment for Node.js core

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

35 stars

Watchers

4 watching

Forks

Latest commit

 

History

47 Commits

Folders and files

Repository files navigation

Node.js Developer Container (devcontainer)

Usage

Setup

Running with Docker Desktop

To run locally on your machine, you'll want to install Docker Desktop and start it up.

It's recommended to use Visual Studio Code with the Dev Containers extension installed, but you can also run the container directly with Docker CLI or the Dev Container CLI, or attach any editor that supports the concept of devcontainers to this container.

Once you've got Docker Desktop running, you can run the following command to pull and start the image:

docker pull nodejs/devcontainer:nightly
docker run -it nodejs/devcontainer:nightly /bin/bash

To use it as a devcontainer, create a .devcontainer/devcontainer.json file in the project with the following content:

{
  "name": "Node.js Dev Container",
  "image": "nodejs/devcontainer:nightly",
  "workspaceMount": "source=${localWorkspaceFolder},target=/home/developer/nodejs/node,type=bind,consistency=cached",
  "workspaceFolder": "/home/developer/nodejs/node",
  "remoteUser": "developer",
  "mounts": [
    "source=build-cache,target=/home/developer/nodejs/node/out,type=volume"
  ],
  "postCreateCommand": "git restore-mtime"
}

For example, to use it with Visual Studio Code, use the "Dev Containers: Reopen in Container" command from the Command Palette (Ctrl+Shift+P or Cmd+Shift+P). After the container is built and started, you should be inside the container with the project mounted in the working directory, while the build cache volume mounted at out/ to speed up builds.

Working in the Container

  • The project is located at /home/developer/nodejs/node. After the container is started, you should be automatically placed in this directory.
  • If you want to build the project in the container, run with ninja (rather than just make):
    • To build the release build, run ninja -C out/Release

    • The container comes with a release build that can be picked up by ninja. As long as your mounted local checkout is not too far behind the checkout in the container, incremental builds should be fast.

    • If you notice that the build is not picking up your changes after checking out a different branch, run git restore-mtime in the container to sync the mtimes of the files in your checkout with the git commit timestamps.

    • You can also set up a git hook to sync the mtime automatically on checkout to keep the build cache effective. From the container, run:

      mkdir -p /home/developer/nodejs/node/.git/hooks
      cp /home/developer/scripts/post-checkout /home/developer/nodejs/node/.git/hooks/post-checkout

      Note that if you install this git hook to your mounted project, and you still wish to run git checkout from you local system, you will need to install git-restore-mtime on your local system as well.

Personal Configuration

Do this from your local system, not in the container. The git configuration will be used in the container since the project is mounted from your local system.

  • Set the git origin to your own fork rather than nodejs/node
    • Example, where USERNAME is your GitHub username: $ git remote set-url origin https://github.com/USERNAME/node.git
    • Verify the remote is valid: git remote -v
  • Set up your git name and email
    • git config --global user.name "YOUR NAME"
    • git config --global user.email "YOUR@EMAIL.TLD"
  • Add your SSH key
  • Preferably one that's already published to GitHub
  • Alternatively, you can install the gh CLI and run gh auth login to login and add a new key.

Development

Some useful commands:

  • docker build . - build the current Dockerfile
  • docker image ls - list the images and IDs
  • docker run -it <image id> - run a container and shell into it
  • docker tag <image id> devcontainer:nightly - run to tag an image as nightly
  • docker build --build-arg NODE_REF=<commit sha> . - build the image from a specific nodejs/node commit

How the nightly images are published

nodejs/node's daily workflow builds main and, when that succeeds, sends a node-daily repository_dispatch event to this repository with the commit SHA it built successfully.

The build workflow then builds and publishes the images from that commit across both platforms (arm64 and amd64) and then tags them both as nightly. If either platform fails, the other is still published as nightly-linux-<arch>, but nightly stays on the previous build until both succeed. A failed automatic run opens an issue labeled nightly-build-failure (or comments on the open one), and the next successful run closes it.

In case the repository_dispatch events stop arriving, a weekly scheduled run builds the tip of the default branch as a fallback. Builds can also be manually triggered using workflow_dispatch from the Actions tab. You can specify a commit SHA (defaults to head of main) and which platform to build (defaults to both of them).

Tips and Tricks for Debugging Failed Builds and Otherwise Developing in This Repo

Some notes on what's been helpful:

  • Break up the RUN statement in the Dockerfile into multiple RUN statements, each containing a single command. This provies more precise information about what exactly is failing if the Docker build fails and isn't providing helpful output.
  • Sometimes removing the RUN statement in the Dockerfile and running docker build, running the built container, and individually running each command in the running container is a better development experience than working outside of the built container.

About

developer environment for Node.js core

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

35 stars

Watchers

4 watching

Forks

Sponsor this project

Used by

Contributors

Languages