Skip to content

Install the Node Agent

Installing the Node.js agent

The Lightrun agent is at the core of the Lightrun platform. It's the component that enables you to add information during runtime, without the need for redeployments or restarts. Before running the agent, it must be installed on the server and its credentials declared inside the application file.

Version Support

The instructions below apply to Node.js v10 and higher. If you require support for earlier versions, please reach out and let us know!

System requirements

Please check the Node.js agent system requirements here.

Lightrun can be installed both directly and inside of a Docker container.

Direct installation

  1. Open a terminal and change to the working directory where your project is located.
  2. Install the Node agent by entering npm install lightrun.
  3. Open your application file (for example, app.js) and add the following code at the beginning of the file.

    require('lightrun').start({
      company: '<COMPANY_NAME>',
      lightrunSecret: '<COMPANY_SECRET>',
      metadata: {
         filename: <FULL_PATH_TO_METADATA_FILE>
      }
    });
    

    Note

    The metadata block with the filename parameter is optional; the agent runs perfectly well without them. Using metadata nevertheless provides substantial benefits when managing your agents. See here for details, with examples, on constructing the metadata file.

  4. Enter the parameter values for company, lightrunSecret , and (optionally) the metadata_file.

  5. Save and close the application file.

  6. From a terminal, enter the command to run your application (for example, node index.js or npm start).

Info

Viewing company details To see the <COMPANY_NAME> and <COMPANY_SECRET> log into the Management Portal and inspect the Install the Agent section, under Getting Started With Lightrun.

Alternative method - Providing agent credentials as environment variables

Note

This method works only for Linux and MacOS.

Info

Although using this method allows you to avoid hard-coding your credentials into the source code, you must enter them in the run command every time your application is launched with the agent.

Instructions

  1. Open a terminal and change to the working directory where your project is located.

  2. Install the Node agent by entering npm install lightrun.

  3. Open your application file (for example, app.js) and add the following code to the beginning of the file:

     require('lightrun').start();
    
  4. Save and close the application file.

  5. From a terminal, enter the command to run your application, with the environment variables declared before the node command.

    COMPANY_SECRET=<COMPANY_SECRET> node --require lightrun/start app.js
    

Running the agent in TypeScript applications

Important

Lightrun for TypeScript requires sourcemap files to be included on the server where the production software is deployed.

Instructions

  1. Insert the following code at the start of your application file (for example, index.ts or app.ts).

    import * as lightrun from 'lightrun';
    
    lightrun.start({
        company: '<COMPANY-NAME>',
        lightrunSecret: '<COMPANY-SECRET>',
        filename: <full_path_to_metadata_file>
    });
    

    Info

    The filename parameter is optional. See here for details on constructing the metadata file.

  2. In the compilerOptions section of the tsconfig.json file, set the parameter "sourceMap" to "true".

  3. From a terminal, run the application.

    node index.js
    

Important

Unless you are working within a TypeScript framework, such as Express or Koa, for the above procedure, you must compile the TypeScript application file.

tsc index.ts

Following compilation, another file is created that has the same name as your TypeScript application, but with the .js extension.

Tip

You can choose to provide the agent's credentials as environment variables, when running your application from the command line, instead of inserting them in the application file, as explained above (note this does not work in MS Windows).

Docker installation

Docker containers are epehmeral.

If you were to create a shell into a Docker container (by docker exec -it <container-id>, for example) and add the Lightrun files there, they would disappear the next time the container would spin up due to the ephemeral nature of that container.

Instead, we suggest you install Lightrun by adding it to the underlying Docker image directly, i.e. by "baking" the agent into the image.

This is an example Dockerfile that installs Lightrun with a simple dummy application:

FROM node:17.5.0
RUN npm install lightrun
COPY prime_main.js /app/prime_main.js
CMD ["node", "prime_main.js"]

If you prefer passing the credentials via the command line, here's how to do it inside a Dockerfile:

FROM node:17.5.0
RUN npm install lightrun
COPY prime_main.js /app/prime_main.js
CMD ["COMPANY_SECRET=<COMPANY_SECRET>", "node", "--require", "lightrun/start", "prime_main.js"]

Important

Installing Lightrun in this fashion does not absolve you of the need to require Lightrun in your application. Please make sure to add Lightrun as an require to your application file.

Running the agent with Express or Koa

If you are using Express or Koa frameworks in your application, refer to the instructions linked below:


Last update: June 19, 2022