@igloosoftware/ig-deploy

 
Igloo CLI

 

ig-deploy

Igloo CLI deploy module. Deploy integrations & themes for the Igloo Platform.

 

Setup

This module can be used in isolation. For developers looking to forgo using the Igloo CLI and create their own application structure, you can use this module to deploy your app.

Add it to your project as a dependency:

# OS X terminal or Windows Command Prompt
npm install --save @igloosoftware/ig-deploy

Require it in your app:

const igDeploy = require('@igloosoftware/ig-deploy');

 

Config

const options = {
  credentials: {
    "account": "",
    "key": "",
    "url": "",
    "provider": ""
  },
  type: 'integration',
  distPath: 'path/to/my-app',
  tmpPath: 'path/to/tmp-folder',
  testRun: false
}

Key	Type	Usage	Value
credentials	Object	Required	Storage account details including: account name, auth key, url & provider.
type	string	Required	Describes the type of asset - currently supported types include: integrations & themes.
distPath	string	Required	Relative or absolute path to your production ready files.
tmpPath	string	Optional	Defaults to your operating systems tmpdir. Optionally provide a path to your project temp folder
testRun	Boolean	Optional	Defaults to false. If true - runs the command but does not deploy/undeploy your asset in the provided storage provider

 

Available Commands

Deploy

This publishes your project to the provided third-party storage provider. Based on the type parameter, it will publish to associated container. For example, type: 'integration' would expect the container integrations to exist.

const igDeploy = require('@igloosoftware/ig-deploy');
const credentials = require('../path/to/credentials.json');

const options = {
  credentials: credentials,
  type: 'integration',
  distPath: './path/to/dist'
}

igDeploy.deploy(options);

Undeploy

This will remove your project from the provided third-party storage provider. It will remove it (based on the provided descriptor id) from the manifest JSON file in the root of the container. It does not however remove the package files, this would require manual deletion through your provider's portal. Different from deploy, you need to pass the id of our asset. Example implementation below where we require the path to the descriptor JSON file.

const igDeploy = require('@igloosoftware/ig-deploy');
const credentials = require('../path/to/credentials.json');
const descriptor = require('../path/to/dist/integration.json');

const options = {
  credentials: credentials,
  type: 'integration',
  id: descriptor.id,
  distPath: './path/to/dist'
}

igDeploy.undeploy(options);

Key	Type	Usage	Value
id	string	Required	Required only when undeploying an asset. used to select the manifest object to be removed.

Validate

This function is invoked as part of deploy, and helps ensure what you're publishing matches the signatures that the Igloo platform expects. It will validate the following:

• that the provided type parameter is supported. Currently we support integrations & themes
• that your projects folder structure is correct. Read more about folder structure for each type below.
• the descriptor JSON file matches the required fields. Read more about descriptors for each type below.

the Validate command is also available on its own, but only requires a sub-set of the original options object:

const igDeploy = require('@igloosoftware/ig-deploy');

igDeploy.validate({
  type: 'integration',
  distPath: 'path/to/dist'
});

 

---

 

Integrations

Folder Structure

This folder is specified in the options object via distPath. It must contain the follow 4 files:

## Your dist folder
integration.json
content.html
thumbnail.png
thumbnailx2.png

Descriptor

integration.json

The following is an example descriptor, which must exist in your distPath. This file must be called integration.json:

{
  "version": "0.0.1",
  "id": "",
  "name": "",
  "description": "",
  "vendorName": "",
  "categories": [],
  "published": "",
  "userConfig": []
}

Descriptor - userConfig Array

The userConfig property mentioned above is represented as an array of objects. Each object represents a user configurable option for your integration. Below are the 4 supported types:

Number

{
  "name": "intParam",
  "label": "Number",
  "type": "number",
  "default": 4,
  "description": "I'm a number"
}

Text

{
  "name": "textParam",
  "label": "Text",
  "type": "text",
  "default": "this is some text",
  "description": "This is a text input"
}

Boolean

{
  "name": "boolParam",
  "label": "Boolean",
  "type": "boolean",
  "default": true,
  "description": "Boolean setting"
}

Choice

{
  "name": "optionParam",
  "label": "Options",
  "type": "choice",
  "description": "Some options to choose from",
  "default": "green",
  "choices": [{
    "value": "blue",
    "description": "Blue"
  }, {
    "value": "green",
    "description": "Green"
  }, {
    "value": "red",
    "description": "Red"
  }]
}

 

Themes

Folder Structure

This folder is specified in the options object via distPath. It must contain, at minimum, the following 3 files:

## Your dist folder
theme.json
css/theme.css
thumbnail.png

Descriptor

theme.json

The following is an example descriptor, which must exist in your distPath. This file must be called theme.json:

{
  "version": "0.0.1",
  "id": "",
  "theme": "",
  "author": "",
  "date": "",
  "external": {
    "js": [],
    "css": []
  },
  "internal": {
    "js": [],
    "css": ["theme.css"]
  }
}

Descriptor - Required Properties

Not all properties in the example above are required when publishing a theme. Below is an example of the minimal requirement:

{
  "version": "0.0.1",
  "id": "my-theme",
  "theme": "My Theme",
  "internal": {
    "css": ["theme.css"]
  }
}

Descriptor - External Dependencies

When publishing a theme, you have the option of including external dependencies via the external object. This accepts URL's to both js & css files:

{
  "external": {
    "js": [
      "https://yoursuperawesomejslibrary.com/too-cool.min.js"
    ],
    "css": [
      "https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css"
    ]
  }
}

Descriptor - Internal Dependencies

Additionally to the required css/theme.css file, you can include project specific JavaScript files:

{
  "internal": {
    "js": [
      "js/theme.min.js"
    ],
    "css": [
      "css/theme.css"
    ]
  }
}

 

---

 

Testing

Tests for ig-deploy are written with Mocha & Chai.

Structure

ig-deploy
|-- test
    |-- integration
    |-- mock
    |-- unit

Unit Tests

./test/unit

From the root directory, run:

npm test

Integration Tests

Automated tests have been written to test the end-to-end experience of deploy & undeploy. This test covers each project type in ./config/module-config.js supportedTypes & each provider – as described in the test file ./test/integration/test-data.json.

The integration test expects a ~/.igloo/credentials.json file to exist, with an environment named igloo-automation for each provider specified in the test file mentioned above. This credentials file is created/edited by the Igloo CLI tool. If you're testing this in an environment without use of the CLI - you will have to manually create the credentials.json file.

From the root directory/ run:

npm run test:automation