Skip to content

Uploading NPL code

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

You have various tools to deploy NPL sources:

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, or if you are starting your project from scratch, start with a readily usable NPL example in GitHub Codespaces or on your local machine.

If you already have NPL source code, jump to section Checking NPL source structure.

Starting from an example

Use the example NPL code provided by the npl-init repository to get a quick start with NPL and NOUMENA Cloud.

Several options are available to you, depending on where you want to keep the example code, for inspection and upload to NOUMENA Cloud:

  • Choose Codespaces if you do not want to install nor copy anything on your machine (requires a GitHub account with Codespaces access).
  • 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 directly 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 in the api/src/main subfolder.

From there, you can proceed directly to upload using the NOUMENA Cloud Portal UI, the 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 directly to upload using the NOUMENA Cloud Portal UI, the NPL CLI, or an IDE NPL-Dev plugin.

To find our more about the example code, check out the Creating a new NPL project tutorial.

Checking NPL source structure

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

.
└── <npl module sources directory> (e.g. api/src/main)
    ├── migration.yml
    ├── npl (see comment about naming below)
    │   ├── <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 (see comment about naming below)
        └── 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 path relative to the migration.yml file must match the values used in the migration.yml file. The npl directory can be named e.g. npl-1.2.3 (versioning pattern in case of migrations) or another name of your choice, but the migration.yml file must refer to the same name in the changeset to be applied. Refer to the Migration descriptor documentation for details.

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 the (optional) party automation rules file (e.g. zip folder 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 ... next to the date of last deployment appearing top right, then Update package

    Uploading the NPL package

    If you are deploying NPL source code again to the same application, make sure to clear the existing package first or implement a migration for the changes to take effect.

    To clear NPL sources from the app, go to the Settings tab in your application view, then select Clear package and confirm with Proceed. Then proceed with Upload package as described above.

  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

Whether you are working in GitHub Codespaces or on your local machine, you can use the NPL CLI to upload NPL sources.

  1. If not already done, install the NPL CLI

  2. Authenticate with NOUMENA Cloud to connect your NPL CLI to your NOUMENA Cloud account:

    npl cloud login

    Follow the authentication prompts to complete the login process. This will store your authentication credentials locally for future deployments.

  3. From the root of your project (e.g. npl-init or my-project if you started from the NPL starter example above), deploy your NPL source code to NOUMENA Cloud with:

    npl cloud deploy npl \
   --tenant YOUR_TENANT_SLUG \
   --app YOUR_APPLICATION_SLUG \
   --migration api/src/main/migration.yml

    Replace YOUR_TENANT_SLUG with your tenant slug and YOUR_APPLICATION_SLUG with your application slug from your NOUMENA Cloud portal. Adjust the path to your migration file as needed. In the absence of --migration parameter, this defaults to the directory from which the command is executed.

    If you are deploying NPL source code again to the same application, make sure to clear the existing package first or implement a migration for the changes to take effect. To clear NPL sources from the app, run:

    npl cloud clear \
    --tenant YOUR_TENANT_SLUG \
    --app YOUR_APPLICATION_SLUG

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

For developers working in VS Code, Cursor, or GitHub Codespaces, direct deployment is supported.

  1. If not already done, install the NPL-Dev plugin for VS Code

  2. Open your project in VS Code (e.g. npl-init or my-project if you started from the NPL starter example above)

  3. In the VS Code sidebar, select the NOUMENA icon to open the NOUMENA Cloud panel

  4. Click Sign in to NOUMENA Cloud, provide your NOUMENA Cloud credentials in the browser window, and select Yes when prompted to Grant Access to PaaS

  5. The NOUMENA Cloud panel of your VS Code editor should now display your NOUMENA Cloud tenants and applications. If not, click the refresh icon

  6. Hover or click on your target application, select Deploy application, then NPL Backend in the action menu

    If you are deploying NPL source code again to the same application, make sure to clear the existing package first or implement a migration for the changes to take effect.

    To clear NPL sources from the app, select the Clear deployed NPL application next to your application in the NOUMENA Cloud panel.

  7. Wait for deployment to complete (indicated by a success message in the VS Code notification area)

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

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

  1. If not already done, install the NPL-Dev plugin for IntelliJ IDEA

  2. Open your project in IntelliJ (e.g. npl-init or my-project if you started from the

    NPL starter example above)

  3. In the top-right corner of IntelliJ, select Current File > Edit Configurations

    Edit configurations in IntelliJ

  4. Choose Add new configuration > Deploy to PaaS

    Deploy to PaaS configuration

  5. 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 the migration.yml file
    • Delete existing application and data before deployment: Check this option to remove any previous deployments and protocol instance.

    You need to select the Delete existing application and data option or write a migration for changes to deployed NPL code to take effect.

  6. Click Ok to save the configuration

  7. In the top-right corner of IntelliJ, click Run Deploy

    Run deployment

  8. Wait for deployment to complete (indicated by a success message in the IntelliJ console)

Verification

Once deployment completes, you'll see the status change in the NOUMENA Cloud Portal. You can also navigate to the Services tab of the application and visit the Swagger UI to check that the NPL code has been deployed successfully.

Next Steps

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