Developing NPL in GitHub Codespaces

Learn how to develop NPL applications using GitHub Codespaces for a cloud-based development environment.

Prerequisites

This track has no prerequisite tracks.

You will need a GitHub account with access to Codespaces.

What is GitHub Codespaces?

GitHub Codespaces provides a cloud-based development environment that runs in your browser or VS Code. It comes pre-configured with all the tools and dependencies needed for NPL development.

Setting up your virtual development environment with Codespaces is especially recommended if you cannot install an IDE and dependencies or run docker containers locally.

Setting up your Codespace

Starting a Codespace

Get started quickly with our pre-configured NPL template:

Open the npl-init repository page
Log into GitHub if not already done
At the top right of the npl-init repository page, click Use this template
Select Open in a Codespace. The Codespace will take a few seconds to open

Codespace Environment

Your Codespace comes pre-configured with:

VS Code - Web-based or desktop integration
NPL CLI - Already installed and ready to use
NPL-Dev for VS Code Extension - NPL syntax highlighting and tooling
Docker - For running the NPL Runtime
Git - For version control

The NPL-Dev for VS Code Extension will prompt you to allow itself to create and maintain AI rules. This configuration helps AI agent follow the NPL syntax closely and generate better code. It is stored in the .cursorrules or .github/copilot-instructions.md files.

Running the npl-init app

Running the NPL Runtime

The NPL Runtime is responsible for running NPL code, managing protocol data, preserving audit trails and exposing interfaces to interact with the NPL code. It is composed of the NPL Engine, NPL Read Model, NPL Audit, and NPL Inspector.

The NPL Engine is the core component that executes the NPL code and manages the protocol data. Other components will be presented in the following tracks.

To start the NPL Engine, run:

docker compose up --wait

The provided configuration runs the NPL Engine in development mode, allowing you to interact with the NPL Engine with an embedded OIDC provider. This removes the need to configure a separate identity service (IAM).

Warning

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

Deploying NPL

To deploy (or re-deploy) your NPL code to the runtime, run:

npl deploy --clear --sourceDir api/src/main

The --clear flag makes sure that previous deployments are automatically removed. If you want to upgrade a running application, please follow the Migration tracks.

Accessing Your Application

The Codespace automatically forwards ports, making your NPL application accessible through generated URLs.

Open the Port forwarding tab of the Panel region by clicking on antenna icon at the bottom of the window.

You will find URLs for the NPL Engine (API service), Keycloak (IAM service), and PostgreSQL (database).

The NPL API provides a REST interface to interact with your deployed protocols. To find exposed endpoints, take the following steps:

Open the NPL Engine URL on port 12000
Select NPL Application in the dropdown in the top right corner

The Using your NPL application tutorial explains how to make use of this page and NPL API.

Storing changes in a GitHub repository

When you create a Codespace from the npl-init template, you're working in a temporary environment. To preserve your work and collaborate with others, you need to store your changes in a GitHub repository.

Creating a new repository

Use the "Publish to GitHub" button at the bottom left of your screen to create a new repo.
Log in to GitHub if not already done. You might need to click the upload to cloud button again.
Follow the interactive commands shown at the top of your screen.

Making and committing changes

To upload changes to your new repository, use the Git left-side pane to stage changed files, create a commit, and publish the changes.

Next Steps

Follow the Using your NPL application starter track