Manage Marketplace Items
There are three main methods to create, modify and delete Marketplace items:
- (recommended) Use
miactl
, the Mia-Platform command line interface tool. - Open an issue on Mia-Platform Github community page.
How to use miactl
to manage the Marketplace
First of all, you need to setup miactl
, as explained in the dedicated doc.
With the miactl marketplace
subcommands, you can perform several actions, described here below.
If you need to handle many Marketplace items, we suggest the adoption of a Declarative Approach.
Create an item
You need to have Company Owner or Project Administrator role at Company level to perform this action
Imagine you are a software developer, working for the Company "Acme Corporation".
You have developed a new service (for example a NodeJS service) called "My Awesome Service". The service is a plugin, i.e. users are only required to configure it and deploy it in their project. You now want it to be available in the Marketplace of your Company.
First of all, you need to create a JSON file as explained in this guide.
Save the file, for example as myAwesomeService.json
file.
The file contents will look like this:
Click to expand myAwesomeService.json
{
"description": "My Awesome Service allows your project to do amazing stuff!",
"documentation": {
"type": "externalLink",
"url": "https://docs.example.org/AwesomeService"
},
"image": {
"localPath": "./awesomeService.png"
},
"name": "My Awesome Service",
"itemId": "my-awesome-service",
"repositoryUrl": "https://git.example.org/awesome-service",
"resources": {
"services": {
"api-portal": {
"componentId": "my-awesome-service",
"containerPorts": [
{
"from": 80,
"name": "http",
"protocol": "TCP",
"to": 8080
}
],
"defaultEnvironmentVariables": [
{
"name": "HTTP_PORT",
"value": "8080",
"valueType": "plain"
}
],
"defaultLogParser": "mia-nginx",
"defaultProbes": {
"liveness": {
"path": "/index.html"
},
"readiness": {
"path": "/index.html"
}
},
"defaultResources": {
"memoryLimits": {
"max": "25Mi",
"min": "5Mi"
}
},
"description": "My Awesome Service allows your project to do amazing stuff!",
"dockerImage": "docker.example.org/awesome-service:1.0",
"name": "awesome-service",
"repositoryUrl": "https://git.example.org/awesome-service",
"type": "plugin"
}
}
},
"supportedBy": "Acme Corporation Inc.",
"supportedByImage": {
"localPath": "./acmeCorporation.png"
},
"tenantId": "acme-corporation",
"type": "plugin"
}
You also want users to write services in your brand new programming language, Acme.Js
.
To do this, you need to create a Template, which is a skeleton with a minimal setup: your users are required to write business code from scratch.
Click to expand myAcmeJsTemplate.json
{
"categoryId": "acmejs",
"description": "This template allows you to start setting up a service written in Acme.Js",
"documentation": {
"type": "markdown",
"url": "https://raw.githubusercontent.com/acme-corporation/Acme-Js-template/master/README.md"
},
"image": {
"localPath": "./acmeJsTemplate.png"
},
"itemId": "acmejs-template",
"name": "Acme.Js Template",
"releaseStage": "",
"resources": {
"services": {
"acmejs-template": {
"archiveUrl": "https://github.com/acme-corporation/Acme-Js-template/archive/master.tar.gz",
"containerPorts": [
{
"from": 80,
"name": "http",
"protocol": "TCP",
"to": 8080
}
],
"defaultEnvironmentVariables": [
{
"name": "HTTP_PORT",
"value": "8080",
"valueType": "plain"
}
],
"defaultLogParser": "mia-nginx",
"description": "This template allows you to start setting up a service written in Acme.Js",
"name": "acmejs-template",
"type": "template"
}
}
},
"supportedBy": "Acme Corporation Inc.",
"supportedByImage": {
"localPath": "./acmeCorporation.png"
},
"tenantId": "acme-corporation",
"type": "example",
"visibility": {
"allTenants": false,
"public": true
}
}
To highlight the potentialities of Acme.Js
and introduce your users to the new programming language, you also decide to provide a working Example with minimal business code.
Click to expand myAcmeJsExample.json
{
"categoryId": "acmejs",
"description": "A simple Hello World example based on Acme Corporation Acme.Js Template.",
"documentation": {
"type": "markdown",
"url": "https://raw.githubusercontent.com/acme-corporation/Acme-Js-example/master/README.md"
},
"image": {
"localPath": "./acmeJsExample.png"
},
"itemId": "acme-js-example",
"name": "TypeScript Hello World Example",
"resources": {
"services": {
"acme-js-example": {
"archiveUrl": "https://github.com/acme-corporation/Acme-Js-example/archive/master.tar.gz",
"containerPorts": [
{
"from": 80,
"name": "http",
"protocol": "TCP",
"to": 3000
}
],
"name": "acme-js-example",
"type": "example"
}
}
},
"supportedBy": "Acme Corporation Inc.",
"supportedByImage": {
"localPath": "./acmeCorporation.png"
},
"tenantId": "mia-platform",
"type": "example",
"visibility": {
"allTenants": false,
"public": true
}
}
Notice that the image
and supportedByImage
objects are populated with local paths to images: make sure the images exist and that their path is correct.
To create the items on the Marketplace, open up a terminal in directory where the files are placed and run this command:
miactl marketplace apply -f myAwesomeService.json -f myAcmeJsTemplate.json -f myAcmeJsExample.json
This command will create the Marketplace items and upload the images along with them.
A message will confirm the operation, returning some information as shown here below:
3 of 3 items have been successfully applied:
ID ITEM ID NAME STATUS
65368hf0c91d871a87afbcbf my-awesome-service My Awesome Service Inserted
65368hf0c91d871a87afvedc acme-js-template Acme.Js Template Inserted
65368hf0c91d871a87afdase acme-js-example Acme.Js Example Inserted
After the upload, the image keys will be replaced with the imageUrl
and the supportedByImageUrl
; to obtain the updated version of an item, use the get
command:
miactl marketplace get 65368hf0c91d871a87afbcbf > myAwesomeService.json
miactl marketplace get 65368hf0c91d871a87afvedc > myAcmeJsTemplate.json
miactl marketplace get 65368hf0c91d871a87afdase > myAcmeJsExample.json
The local file fields won't be updated after the item creation. We recommend to always download a new copy afterwards to keep your local copy up to date.
From now on, the items you created will be visible as a clickable card inside the Internal Company Marketplace section of the Console.
For example, here is "My Awesome Service"'s card:
Further information about the apply
command can be found in the dedicated doc.
Update an item
You need to have Company Owner or Project Administrator role at Company level to perform this action
Imagine now that you noticed that the description of "My Awesome Service" is not correct and you want to change it.
First of all, download and save the latest version of the item configuration:
miactl marketplace get ITEM_ID > myAwesomeService.json
where ITEM_ID
is an alphanumerical id of the Marketplace item.
If you don't know the item id, use the miactl marketplace list
command to list all the Marketplace Items. You can easily locate the one of interest by looking for its name.
It is suggested to always download the Marketplace item just before updating it to make sure it works on the latest version.
Edit your file following the steps described in the Modifying the Marketplace Item; once you are happy with the changes, save the file and apply it to the Marketplace:
miactl marketplace apply -f myAwesomeService.json
You will see the outcome of the operation in the command output:
1 of 1 items have been successfully applied:
ID ITEM ID NAME STATUS
65368hf0c91d871a87afbcbf my-awesome-service My Awesome Service Updated
The changes are now reflected to the Console.
Delete an item
You need either the Company Owner or Project Administrator role at Company level to perform this action
Imagine you notice that the service "My Awesome Service" is no longer useful for your Company and so you want to delete it.
You can delete an item from the Marketplace by means of the delete
command:
miactl marketplace delete --object-id=<objectId>
The
object-id
is theID
you get when you apply the template, it is not theitemId
The item is then deleted from the Marketplace.
The deletion is permanent, but the file on your machine will not be deleted. If you want, you can recreate the item on the Marketplace again by applying the file.
Open an issue on Mia-Platform Github community page
To contribute to the Mia-Platform Marketplace using this method, start by opening an issue here. This issue will outline the necessary information for your request. Subsequently, a Mia-Platform representative will take over the issue and contact you to collaboratively plan the addition of the component to the Mia-Platform Marketplace, following the guidelines described on this documentation page.