Skip to content

Uploading NPL code

This section explains how to deploy your NPL application code to the NOUMENA Cloud.

You can deploy NPL sources through the web portal, from command line, or directly from a local IDE or GitHub Codespaces.

Deployment tool Project code in GitHub Codespace Project code on local machine
Portal (zip upload) ✅
Command line (NPL CLI) ✅ ✅
VS Code NPL-Dev plugin ✅ ✅
IntelliJ NPL-Dev plugin ✅

If you are new to NPL and NOUMENA Cloud, start with sample NPL code in GitHub Codespaces (requires a GitHub account with Codespaces access) or on your local machine.

Preparing your NPL sources

If you already have NPL source code, check that it conforms to the expected structure.

If you are starting from scratch, jump to the next section to use an example package.

Structure of NPL sources

Your NPL sources should have the following elements for inclusion in an NPL deployment to NOUMENA Cloud:

.
└── <npl module sources directory> (e.g. api/src/main)
    ├── migration.yml
    ├── npl
    │   ├── <npl package> (e.g. greetings)
    │   │   ├── <npl source file> (e.g. hello.npl)
    │   │   └── <npl source file> (e.g. bye.npl)
    │   └── <npl package>
    │       └── <npl source file>
    └── rules
        └── rules.yml (optional)

Key files and folders in the structure are:

  • migration.yml: Migration descriptor file to manage application code migrations, required for any deployment
  • npl: NPL sources, required for any deployment
  • rules.yml: Party Automation descriptor file to enable the automatic creation of parties using the attributes in the user's authorization token (optional)

The naming of the npl directory and rules.yml file and their and path relative to the migration.yml file must match the values used in the migration.yml file.

Starting from an example project

If you are starting from scratch, you can use the example NPL code provided by the npl-init repository. Several options are available to you, depending on where you want to inspect the code or upload it from:

  • Choose Codespaces if you do not want to install nor copy anything on your machine.
  • If you prefer to work on your machine, create a local copy of the example project using the NPL CLI or zip file download.
  1. Open the npl-init repository page
  2. Log into GitHub if not already done
  3. At the top right of the npl-init repository page, click Use this template
  4. Select Open in a Codespace. The Codespace will take a few seconds to open

Among other things, your Codespace comes pre-configured with

  • the NPL CLI, which allows deployment from the Codespace console
  • the NPL-Dev plugin for VS Code, which allows deployment from the Codespace GUI

Browse the NPL source code in the Codespace File panel, and proceed to upload NPL with the NPL CLI or with the VS Code NPL-Dev plugin.

To learn more about developing NPL in GitHub Codespaces, check out this starter tutorial.

  1. If not already done, install the NPL CLI
  2. In a terminal window, create a copy of the standard NPL example project with:

npl init --projectDir my-project
This command will create a new directory called my-project containing the example NPL package, with the appropriate structure for upload to NOUMENA Cloud.

From there, you can proceed to upload using the the NOUMENA Cloud Portal UI, NPL CLI, or an IDE NPL-Dev plugin.

  1. Download the npl-init project as zip file
  2. Unzip the file on your machine.

The unzipped folder contains the example NPL package, with the appropriate structure for upload to NOUMENA Cloud in the api/src/main subfolder.

From there, you can proceed to upload using the the NOUMENA Cloud Portal UI, NPL CLI, or an IDE NPL-Dev plugin.

Uploading NPL sources

Option 1: Upload NPL from the NOUMENA Cloud Portal

Using the NOUMENA Cloud Portal, you can manually upload NPL sources stored on your local machine.

  1. Create a zip archive of the NPL sources folder containing the migration.yml file, the .npl files and (optionally) the party automation rules file (e.g. zip api/src/main in the npl-init example project)

  2. Navigate to the application in the NOUMENA Cloud Portal

  3. Select Upload package from the top-right corner. If you have previously deployed NPL sources, select ... right of the date of last deployment appearing top right, then Update package. Uploading the NPL package

  4. Browse to select the zip file created in step 1, and click Upload

  5. Wait for deployment to complete (indicated by a success message)

Option 2: Upload NPL with the NPL CLI

Option 3: Upload NPL with the VS Code NPL-Dev plugin

Option 4: Upload NPL with the IntelliJ NPL-Dev plugin

For developers working in IntelliJ IDE, direct deployment is supported.

  1. Open your project in IntelliJ (e.g., npl-app). New projects can be setup following the developing NPL on your own machine.

  2. Under npl/src/main, ensure that the npl folder is versioned, like npl-1.0.0. Rename it to npl-1.0.0 otherwise.

The version suffix is required for the NOUMENA Runtime to identify the source code folder

  1. Ensure there's a yaml folder under npl/src/main containing a migration.yml file with the following content:
systemUnderAudit: npl-app

changesets:
  - name: 1.0.0
    changes:
      - reset: true
      - npl-load:
        dir-list: npl

This configuration specifies:

  • The system name (npl-app)
  • The version name (1.0.0) matching the folder ending
  • The directory containing NPL code (npl) matching the folder name beginning

  • Reset flag to clear any previous deployments

  • In the top-right corner of IntelliJ, select Current File > Edit Configurations Edit configurations in IntelliJ

  • Choose Add new configuration > Deploy to PaaS Deploy to PaaS configuration

  • Configure the deployment with:

  • Name: "Deploy"

  • Server base URL: https://portal.noumena.cloud
  • Application ID: Found on the settings tab of your app in the NOUMENA Cloud Portal
  • Username: Your NOUMENA Cloud email address
  • Password: Your NOUMENA Cloud password
  • Source path: The absolute path to the main directory containing npl and yaml folders

  • Delete existing application and data before deployment: Check this option to remove any previous deployments and protocol instance

  • Click Ok to save the configuration

  • In the top-right corner of IntelliJ, click Run Deploy Run deployment

  • Return to the NOUMENA Cloud portal to verify deployment status

Verification

Once deployment completes, you'll see the status change in the portal. You can also navigate to the Services tab to check that all components have deployed successfully.

Next Steps

Now that your NPL application is deployed, continue to Creating users in Keycloak to set up authentication for your application.