Developing NPL on your own machine

Prerequisites

This track has no prerequisite tracks.

You will need your favorite editor, docker compose and the NPL CLI.

You can install the NPL CLI using

curl -s https://documentation.noumenadigital.com/get-npl-cli.sh | bash

or download the latest release here and add it to your $PATH.

Writing NPL

NPL can be written in any code editor you’d like. We currently provide plugins for IntelliJ, VSCode and Cursor. The last two are based on the NPL language server. If you want to use the language server in another editor, check our forum for unofficial support. Currently, the IntelliJ plugin is the only one supporting live debugging in sandbox mode.

For initial exploration, you can download the npl-init repository using the following command. Replace REPO_NAME (twice) with the name of the folder you want to create.

mkdir REPO_NAME && \
curl -sL https://api.github.com/repos/NoumenaDigital/npl-init/tarball \
  | tar xz --strip-components=1 -C REPO_NAME

Then open the created folder in your editor of choice. The npl-init repository contains a simple NPL application modelling a counter protocol. It is a good starting point to understand how NPL works and how to structure your NPL code.

If your terminal is not in the folder where you created the npl-init repository, navigate to it using the cd command.

cd REPO_NAME

To run the unit tests that come with these examples from your terminal, use

npl test

The NPL Runtime

NPL compiles to bytecode and requires the NPL Runtime to execute. During development, you will likely upload your NPL directly to a running runtime, but we support other deployment methods as well.

To get started, the docker-compose.yml file provides a DEV_MODE configuration for the engine.

Running the engine in development mode will allow you to interact with the engine with an embedded OIDC provider. This removes the need of having to configure an IAM service. Start the engine using:

docker compose up --wait

Warning

ENGINE_DEV_MODE is for development purposes only. Running this in production is a huge security risk.

Deploying NPL

Once your runtime is up and running, you use the NPL CLI to deploy NPL code to your engine. The .npl/deploy.yml file contains a local configuration to deploy to the local engine.

You can deploy your NPL to the runtime using

npl deploy --sourceDir src/main

After a successful deployment, you will find your protocols exposed as a service on http://localhost:12000/swagger-ui/ and selecting the NPL Application in the top right corner.

The NPL API provides a REST interface to interact with your deployed protocols. You can use the drop-down menu to select the package and protocol you want to interact with. The API will automatically generate the required endpoints.

Next steps

Follow the Using your application track to understand more about interacting with your NPL service.