# @igloosoftware/ig-deploy

> Igloo Deploy allows for validating and deploying apps for the Igloo ecosystem.

Latest version **0.5.5** (published 2020-04-01) · SEE LICENSE IN LICENSE.txt license · 0 weekly downloads

## Install

```sh
npm install @igloosoftware/ig-deploy
pnpm add @igloosoftware/ig-deploy
yarn add @igloosoftware/ig-deploy
bun add @igloosoftware/ig-deploy
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.5.5 |
| Published | 2020-04-01 |
| First published | 2017-09-06 |
| Weekly downloads | 0 |
| License | SEE LICENSE IN LICENSE.txt |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=8.0.0 |
| Dependencies | 9 |
| Unpacked size | 69.4 KB |
| Known vulnerabilities | 0 (+2 in 1 direct dependencies) |
| Install scripts | no |
| Author | Igloo Software |
| Maintainers | aaaron, brianatigloo, iglooadmin, mattbrodrecht, wmacdonald |

## Links

- npm: https://www.npmjs.com/package/@igloosoftware/ig-deploy
- npm.io page: https://npm.io/package/@igloosoftware/ig-deploy

## Dependencies (9)

- [i](https://npm.io/package/i.md) ^0.3.5
- [ajv](https://npm.io/package/ajv.md) ^4.11.8
- [path](https://npm.io/package/path.md) ^0.12.7
- [chalk](https://npm.io/package/chalk.md) ^2.3.0
- [debug](https://npm.io/package/debug.md) ^3.1.0
- [lodash](https://npm.io/package/lodash.md) ^4.17.2
- [fs-extra](https://npm.io/package/fs-extra.md) ^4.0.3
- [superagent](https://npm.io/package/superagent.md) ^3.1.0
- [@igloosoftware/ig-azure](https://npm.io/package/@igloosoftware/ig-azure.md) ^0.3.6

## Recent versions

- 0.5.5 (latest) — 2020-04-01
- 0.5.3 — 2018-03-26
- 0.5.1 — 2017-11-28
- 0.4.4 — 2017-10-11
- 0.4.3 — 2017-09-06

## README

<p>
    <img src="https://igloodeveloperassets.azureedge.net/npm/igloo-cli/logo.png"><br />
    <strong>Igloo CLI</strong>
</p>

&nbsp;<br />

ig-deploy
------------------

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


&nbsp;<br />

### 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:

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

Require it in your app:

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

&nbsp;<br />

### Config

```javascript
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. |


&nbsp;<br />

### 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.

```javascript
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.

```javascript
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:

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

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

&nbsp;<br />

----

&nbsp;<br />

### Integrations

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

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

| File            | Dimensions |
|:----------------|:-----------|
| thumbnail.png   | 64x64px    |
| thumbnailx2.png | 128x128px  |


#### Descriptor

*integration.json*

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

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

| Key         | Type   | Usage    | Value                                                                                                                                    |
|:------------|:-------|:---------|:-----------------------------------------------------------------------------------------------------------------------------------------|
| version     | string | Required | The version of your application.                                                                                                         |
| id          | string | Required | Unique identifier for your application. Used when interfacing with an Igloo community.                                                   |
| name        | string | Required | The user facing label for your application in an Igloo community.                                                                        |
| description | string | Required | Meant to provide additional useful information about your application.                                                                   |
| vendorName  | string | Required | The name of the service/organization your application integrates with. For example: Google Calendar, Salesforce, Zendesk etc.            |
| categories  | Array  | Optional | Optionally include an array of category strings to group your applications with others on the administration side of an Igloo community. |
| published   | string | Optional | A datetime stamp when your application was published.                                                                                    |
| groups      | Array  | Optional | An array of objects describing groups to organize your applications userConfig options.  More details below.                             |
| userConfig  | Array  | Optional | An array of objects describing the configuration options you can surface to the end user. More details below.                            |


#### Descriptor - groups Array

The `groups` property is represented as an array of objects.  Each object represents a group heading that can be used to create logical separation for larger lists of `userConfig` options.  These groups `name` property must match at least one `userConfig` options `group` property in order to be displayed to the user.

```json
{
  "name": "group-one",
  "label": "Group One",
  "collapse": false
}
```

| Key      | Type    | Usage    | Value                                                                                                                           |
|:---------|:--------|:---------|:--------------------------------------------------------------------------------------------------------------------------------|
| name     | string  | Required | Unique identifier for your group header. Match this property value with the `group` property on a `userConfig` option.          |
| label    | string  | Required | The user facing name of your group header.                                                                                      |
| collapse | boolean | Optional | Defaults to false. Optionally set to true to turn the group header into a collapsable section in the user facing widget config. |


#### Descriptor - userConfig Array

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

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

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

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

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

| Key         | Type    | Usage    | Value                                                                                                                  |
|:------------|:--------|:---------|:-----------------------------------------------------------------------------------------------------------------------|
| name        | string  | Required | Unique identifier for the input.                                                                                       |
| label       | string  | Required | User-friendly name used to describe the input to the user.                                                             |
| type        | string  | Required | Must match 1 of 4 available types shown above: number, text, boolean, choice.                                          |
| default     | string  | Required | A default value for the input. Must match the option **type**.                                                         |
| description | string  | Optional | Optionally include additional information describing the input. Displayed as help text to the user, next to the input. |
| required    | boolean | Optional | Defaults to true. If set to false, the input will be included in an "Additional Options" menu to the user.             |
| group       | string  | Optional | Optionally group the input with others in the user facing widget config.                                               |

&nbsp;<br />

### Themes

#### Folder Structure

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

```shell
## 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`:

```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:

```json
{
  "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:

```json
{
  "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:

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

---
_Source: https://npm.io/package/@igloosoftware/ig-deploy · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._