Node.js in a container

In this guide you will learn how to:

  • Create a Dockerfile file for an Express Node.js service container
  • Build, run, and verify the functionality of the service
  • Debug the service running within a container

Prerequisites

  • Both Docker and the VS Code Docker extension must be installed as described in the overview
  • Node.js version 10 or later

Create an Express Node.js application

  1. Create a folder for the project.

  2. Open a development command prompt in the project folder and create the project:

    1. npx express-generator
    2. npm install

Add Docker files to the project

  1. Open the project folder in VS Code.

  2. Open the Command Palette (kb(workbench.action.showCommands)) and use Docker: Add Docker Files to Workspace… command:

    Add Dockerfile to a Node.js project

  3. Select Node.js when prompted for the application platform.

  4. Select either Yes or No when prompted to include Docker Compose files.

    The Docker Compose files are optional and not used for debugging the application within a container, so either is a valid choice.

  5. Enter 3000 when prompted for the application port.

The extension will create Dockerfile and .dockerignore files. If you elected to include Docker Compose files, docker-compose.yml and docker-compose.debug.yml will be generated as well. Finally, the extension will create a set of VS Code tasks in .vscode/tasks.json for building and running the container (in both debug- and release-configurations) and a launch debug configuration in .vscode/launch.json for debugging the service within the container.

Run the service locally

  1. Open a terminal (kb(workbench.action.terminal.toggleTerminal)).

  2. Enter npm run start to start the application:

    1. > express-app@0.0.0 start /Users/user/code/scratch/express-app
    2. > node ./bin/www

  3. Open the web browser and navigate to http://localhost:3000. You should see a page similar to the following:

    Application page in browser

  4. When done testing, type kbstyle(Ctrl+C) in the terminal.

Build the service image

  1. Open the Command Palette (kb(workbench.action.showCommands)) and select the Docker Images: Build Image… command.

  2. Open the Docker view and verify that the new image is visible in the Images tree:

    Verify Docker image exists

Run the service container

  1. Right-click on the image built in the previous section and select Run or Run Interactive. The container should start and you should be able to see it in the Docker Containers tree:

    Running service container

  2. Open the web browser and navigate to http://localhost:3000. You should see a page similar to the following:

    Application page in browser

  3. When done testing, right-click the container in the Containers tree and select Stop.

Debug in the service container

When the Docker extension adds files to the application, it also adds a VS Code debugger configuration in .vscode/launch.json for debugging the service when running inside a container. The extension detects the protocol and port used by the service and points the browser to the service.

  1. Set a breakpoint in the get() handler for the '/' route in routes/index.js.

  2. Make sure the Docker Node.js Launch debugger configuration is selected.

    Selected Docker debug configuration

  3. Start debugging (use the kb(workbench.action.debug.start) key).

    • The Docker image for the service builds.
    • The Docker container for the service runs.
    • The browser opens to the (random) port mapped to the service container.
    • The debugger hits the breakpoint in index.js.

    Note that, because the debugger attaches after the application starts, the breakpoint may missed the first time around; you might have to refresh the browser to see the debugger break on the second try.

    You can configure the application to wait for the debugger to attach before starting execution by setting the inspectMode property to break in the docker-run: debug task in tasks.json.

Next steps

You’re done! Now that your container is ready, you may want to: