Reviewers:

Overview:

The Add-On Mart Tool is a CLI-based application designed to simplify new application deployment and the submission of attributes for review.

Once reviewed by PortaOne staff, the application can be deployed to the PortaOne infrastructure.

Application:

Download latest version of the addon-mart tools for your OS : https://gitlab.portaone.com:8949/read-only/microservices-tools-addonmart/-/releases

Requirements:

1) Attributes for Deployment:

Module schema (Instruction , Schema Generator tool)
Helm charts ( Helm Charts guide )
Docker images
Auto-deployer templates
Other attributes (description, logos...)

2) Upload to Registry: Docker images and Helm charts must be uploaded to the registry beforehand using either the "local" or "staging" context.

3) Context Configuration: The Add-On Mart must be configured for the "production" context (Context (environment) selection).

4) Tool Preconfiguration: Ensure the Add-On Mart tool is preconfigured with the required parameters (server URL, registry data, vendor credentials, etc.) for the "production" context.

(Configure application)

Context (environment) selection

There is three possible contexts (environments) in which the application can proceed:

local
staging
production

Each context stores configuration file data (URLs, registry name, etc.) that corresponds to the specific environment.

Each environment has a unique list of allowed commands.

Command to set/change context:

To switch between contexts, execute the command addon-mart set-context <context>.

Example

> addon-mart set-context production

INFO: Set context to "production"
SUCCESS: Configuration file was updated

After proceeding with the command stated above, the context in the application configuration file shall be changed.

After changing the context, the user can see the "help" output for a list of commands that are assigned to a selected environment.
Use "addon-mart -h" to see all possible commands

> addon-mart -h
NAME:
   addon-mart - A CLI program to manage Add-on Mart modules

USAGE:
   addon-mart [global options] command [command options] 

VERSION:
   latest

DESCRIPTION:
   Current context: production (environment)

COMMANDS:
   get-app-settings  Displays the "addon-mart" application configuration settings
   set-app-settings  Allows to update settings in "addon-mart" application configuration file
   set-context       Set the context (environment)
   publish-module    Publish a new application module version to the review
   help, h           Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h     show help
   --version, -v  print the version

COPYRIGHT:
   © 2001 - 2025 PortaOne Inc.

Configuring the application:

The Add-On Mart tool creates an internal application configuration file during its first execution.

If a configuration file already exists, its values are read during subsequent uses of the application.

Configuration files are stored in the following directories, depending on the operating system:

On Unix systems:

$XDG_CONFIG_HOME/AddonMartTool/config.json
$HOME/.config/AddonMartTool/config.json

On Darwin:

$HOME/Library/Application Support/AddonMartTool/config.json.

On Windows:

%AppData%\AddonMartTool\config.json

Configuration file example:

{
    "configuration": {
        "context": "staging" 										## Currently selected context
    },
    "local": { 														## local context configuration
        "server_config": { 											## Configuration of Configuration Backend Server
            "server_url": "https://ipaas-testenv.portaone.com",			## Configuration Backend server URL 
            "instance_tag": "demo" 									## Deployment tag (Default during first application initialization - demo)
        },
        "registry_config": { 										## Configuration of image/charts registry 
            "registry_hostname": "registry.portaone.com", 			## Hostname of the remote registry 
            "docker_repository_name": "vendor_name", 				## Name of the remote image registry
            "charts_repository_name": "vendor_name" 				## Name of the remote chart repository
        }
    },
    "staging": { 													## staging context configuration
        "credentials": { 
            "login": "vendor_name", 								## Vendor login to access Configuration Backend service and image/charts registry
            "password": "vendor_password" 							## Vendor password to access Configuration Backend service and image/charts registry 
        },
        "server_config": { 											## Configuration of Configuration Backend Server
            "server_url": "https://ipaas-testenv.portaone.com", ## Configuration Backend server URL
            "instance_tag": "demo" 									## Deployment tag (Default during first application initialization - demo)
        },
        "registry_config": { 										## Configuration of image/charts registry
            "registry_hostname": "registry.portaone.com", 			## Hostname of the remote registry  
            "docker_repository_name": "vendor_name", 				## Name of the remote image registry
            "charts_repository_name": "vendor_name" 				## Name of the remote chart repository

        }
    },
    "production": { 												## production context configuration
       "credentials": { 
            "login": "vendor_name", 								## Vendor login to access Configuration Backend service and image/charts registry
            "password": "vendor_password" 							## Vendor password to access Configuration Backend service and image/charts registry 
        }, 
       "server_config": { 											## Configuration of Configuration Backend Server
            "server_url": "https://ipaas.portaone.com", 			## Configuration Backend server URL
            "instance_tag": "demo" 									## Deployment tag (Default during first application initialization - demo)
        },
        "registry_config": { 										## Configuration of image/charts registry
            "registry_hostname": "registry.portaone.com", 			## Hostname of the remote registry  
            "docker_repository_name": "vendor_name", 				## Name of the remote image registry
            "charts_repository_name": "vendor_name" 				## Name of the remote chart repository

        }
    }
}

Command to set/change configuration parameters:

The addon-mart set-app-settings command allows updating data in the application configuration file.

This command is essential for ensuring that the application configuration settings are accurate and up to date for the specified context (environment).

To update the application configuration file, use the command addon-mart set-app-settings [command options] [argument]

Use --help to see more details related to the command.

> addon-mart set-app-settings -h
NAME:
   addon-mart set-app-settings - Allows to update settings in "addon-mart" application configuration file

USAGE:
   addon-mart set-app-settings [command options] [arguments...]

OPTIONS:
   --context value           Context in which data should be set/updated (required)
   --login value             Login for authentication in the server and registry ("staging" context only)
   --password value          Password for authentication in the server and registry ("staging" context only)
   --server-url value        URL of the configuration backend server
   --instance-tag value      Deployment tag (Default: demo)
   --registry-addr value     Hostname of the remote registry
   --docker-repo-name value  Name of the remote docker repository or image registry
   --charts-repo-name value  Name of the remote chart repository
   --help, -h                show help

Command example for production context:

Example

> addon-mart set-app-settings --context production \
--login p1_sagitario \
--password <vendor_password> \
--server-url https://ipaas-testenv.portaone.com \
--instance-tag demo

Command example for local context:

Can be configured to push docker images and Helm Charts to the PortaOne registry using local context.

Example

> addon-mart set-app-settings --context local \
--server-url https://ipaas-testenv.portaone.com \
--instance-tag demo \
--registry-addr registry.portaone.com \
--docker-repo-name p1_sagitario \
--charts-repo-name p1_sagitario

Command to check configuration parameters:

The addon-mart get-app-settings command allows to display configuration data to the cli output.

This command allows displaying either the complete application configuration or the configuration specific to the currently set context.

It also provides an option to display the configuration data in JSON format.
Use --help to see more details related to the command.

> addon-mart get-app-settings -h
NAME:
   addon-mart get-app-settings - Displays the "addon-mart" application configuration settings

USAGE:
   addon-mart get-app-settings [command options] [arguments...]

OPTIONS:
   --current   Displays current application configuration (default: false)
   --raw       Display the raw JSON configuration (default: false)
   --help, -h  show help

Command example:

Example

> addon-mart get-app-settings
#OR
> addon-mart get-app-settings --current
#OR
> addon-mart get-app-settings --raw

Docker Image and Helm charts uploading:

Before publishing a module for review, Helm charts, and Docker images must be uploaded to the PortaOne registry (Harbor).

If the module was previously tested on the TEAM environment, it is likely that attributes such as Helm charts and Docker images have already been published to the Harbor registry using the command addon-mart sync.

For more details related to publishing attributes to the PortaOne registry within the TEAM scope, please refer to the following link: How to use Add-On Mart Tool for Testing environment (TEAM).

If the image and Harbor registry attributes were not previously published, they can be uploaded using addon-mart tool with "local" context.

Make sure that the application was configured for local context → Configuration file Example

To do so, please:

Select the local context.
Execute the command: addon-mart push.

> addon-mart set-context local

> addon-mart push -h
NAME:
addon-mart push - Allows to push docker images or Helm charts to the registry

USAGE:
addon-mart push [command options] [arguments...]

OPTIONS:
--image value [ --image value ] Name of the Docker image with tag. This flag can be specified multiple times.
Format options:
- <image name>:<local tag> (local tag and remote tag are equal)
- <image name>:<local tag>:<remote tag>
--chart-dir value Path to the directory with valid Chart.yaml
--login value Login for authentication in the registry (required)
--password value Password for authentication in the registry (overrides ADDON_MART_REGISTRY_PASSWORD env variable)
--help, -h show help

Publishing module for review:

Modules can be published for review using CLI flags or by providing a JSON/YAML extended module schema.

Take into account that the configuration schema and Helmfile (auto-deployer) templates must be prepared before executing the command. These parameters are mandatory.

More details about preparing the module configuration schema can be found by following these links: - Instruction , Schema Generator tool

Additionally, information related to schema preparation and Helmfile (auto-deployer) template preparation can be found in the Guide to deploy application in Add-On Mart for third-party developers.

Schema - Step 2: Prepare a Config Schema for the Module

Templates - Step 6: Prepare helmfile - Auto-Deployer template

All mandatory parameters must be provided.

If a parameter differs from the data currently stored in the PortaOne infrastructure, the data will be overwritten to match the values specified in the last executed command.

Publishing for review using CLI flags

> addon-mart publish-module cli \
  --module_name <module name> \
  --documentation <documentation(Text/URL)> \
  --configuration-guide <configuration guide(Text/URL)> \
  --extended-description <extended description(Text/URL)> \
  --description <description(Text/URL)> \
  --inline-logo <logo(URL)> \
  --inline-logo-tile <logo(URL)> \
  --multi-instance <true/false>
  --config-ui <config_ui(URL)> \
  --version <module version> \
  --labels <released version label> \
  --labels <released version label> \
  --labels <released version label> \
  --release-notes <release notes(Text/URL)> \
  --configuration-schema <path/to/config_schema.json> \
  --templates <path/to/templates>

For more details, please refer to the command help

> addon-mart publish-module cli -h
NAME:
   addon-mart publish-module cli - Publish a new module version using CLI flags

USAGE:
   addon-mart publish-module cli [command options] [arguments...]

OPTIONS:
   --module_name value                Name of the module (required)
   --documentation value              Text or URL to the documentation for the module (required)
   --configuration-guide value        Text or URL to the configuration guide for the module
   --extended-description value       Text or URL link to the extended description of the module
   --description value                Text or URL to the brief description of the module (required)
   --inline-logo value                URL link to the inline logo (required)
   --inline-logo-tile value           URL link to the tile logo (required)
   --multi-instance value             Set if module is multi-instance (default: "true")
   --config-ui value                  URL link to configuration portal (Universal Config UI - https://ipaas.portaone.com/ipaas-config-ui/)
   --version value                    Version of the application (required)
   --labels value [ --labels value ]  Labels for the released version (e.g., stable,latest). This flag can be specified multiple times
   --release-notes value              Text or URL to the release notes
   --configuration-schema value       Path to a file with application configuration-schema. Note: this file should be in JSON (.json) format (required)
   --templates value                  Path to a directory with templates (required)
   --help, -h                         show help

Publishing for review using extended module schema file

The extended module schema can be prepared in one of the following formats:

JSON
YAML

Extended module schema (JSON)

{
    "name": "PortaPhone",
    "documentation": "https://www.portaone.com/add-on-mart-modules/portaphone/",
    "configuration_guide": "https://www.portaone.com/add-on-mart-modules/portaphone/",
	"description": "PortaPhone is a WebRTC app that runs in your browser, mobile (iOS & Android) or Microsoft Teams as an OTT app running in a Teams tab. It includes the ability for calling, call history, and phonebook/enterprise directory, as well as video calls. This app can be white-labeled (for a fee).",
    "extended_description": "extended description",
	"inline_logo_url": "https://drive.google.com/uc?id=1Q_yQoGJzXK-WBedK5nn5tc5dNav4nibh",
    "inline_logo_tile_url": "https://drive.google.com/uc?id=1ngv9kYZb0dEOEuI0pwiH-x625iJTO-na",
    "multi_instance": true,
    "config_ui": "https://portaphone.addonmart.porta.one/version-test",
    "version_details": {
        "version": "0.5.0",
        "labels": [
            "stable",
            "latest"
        ],
        "release_notes": "https://www.portaone.com/add-on-mart-modules/portaphone/"
    }
}

OR

Extended module schema (YAML)

name: "PortaPhone"
documentation: "https://www.portaone.com/add-on-mart-modules/portaphone/"
configuration_guide: "https://www.portaone.com/add-on-mart-modules/portaphone/"
description: "PortaPhone is a WebRTC app that runs in your browser, mobile (iOS)"
extended_description: "extended description",
inline_logo_url: "https://drive.google.com/uc?id=1Q_yQoGJzXK-WBedK5nn5tc5dNav4nibh"
inline_logo_tile_url: "https://drive.google.com/uc?id=1ngv9kYZb0dEOEuI0pwiH-x625iJTO-na"
multi_instance: true
config_ui: "https://portaphone.addonmart.porta.one/version-test"
version_details:
  version: "0.5.0"
  labels:
    - stable
    - latest
  release_notes: "https://www.portaone.com/add-on-mart-modules/portaphone/"

After preparing the module configuration schema, Helmfile (auto-deployer) templates, and extended module schema, version can be submitted for review by using the command:

Send for review

addon-mart publish-module file \
  --extended-module-schema <path/to/extended-module-schema.json> \
  --configuration-schema <path/to/config_schema.json> \
  --templates <path/to/templates>

Response

200 OK
{
    "status": "PortaPhone version 0.5.0 successfully submitted for review"
}

If any validation error occurs during schema publishing, corresponding attributes have to be adjusted.

If no errors occur, the module version was successfully pushed to the Add-On Mart infrastructure.

Page tree

How to use Add-On Mart Tool for Production environment

Application:

Requirements:

Context (environment) selection

Configuring the application:

Docker Image and Helm charts uploading:

Publishing module for review:

Publishing for review using CLI flags

Publishing for review using extended module schema file