# Blueprints

### Introduction

An application blueprint is a packaged tarball file (`*.tar.gz`) that contains the application manifest YAML file (`jovianx.yaml`) and the Helm Charts directories that are referenced by the application manifest. The application manifest defines the components used by the application. The components can be Helm Charts or other cloud-managed services. JovianX uses the Application Blueprint to create resources and set up services when a new account signs up.

### Blueprint Structure

The application blueprint contains the following:

1. **Application Manifest** - The application manifest  is a YAML file named `jovianx.yaml`. The manifest defines the components that are created for a new SaaS account. For example Kubernetes Helm Charts, DynamoDB, CloudDNS or other cloud managed services.
2. **Helm Charts -** The blueprint can also include the Helm Charts that are used for creation of application services.

### Application Manifest(`jovianx.yaml`)

The application manifest is a YAML file that describes the application. JovianX uses the manifest to create the needed resources and services when a new account signs-up.

A basic template of an application manifest looks as following:

{% code title="jovianx.yaml" %}

```yaml
# v1 - JovainX API Compatability
jovianx_api_version: v1

# string - Name of this SaaS application
application_name: '<APP-NAME>'

# semantic versioning - version of this JovianX blueprint 
version: <SEM-VERSION>

# string - Name of a component to be used a main application entry point 
main_endpoint_component: '<COMPONENT-NAME>'

# Components section defines all application components and their helm chart implementations
components:
  - name: '<COMPONENT-NAME>'
    version: <COMPONENT-SEMVER>
    provider: helm_chart
    helm_chart_name: <PATH/TO/HELM/CHART>
    helm_set:
      # List of key-value pairs to pass to helm on account creation
      - key: '<SET-KEY>'
        value: '<SET-VALUE>'
    endpoints:
      - name: '<ENTRYPOPINT-NAME>'
        type: entry_point
        service_name: '<KUBERNETS-SERVICE-NAME>'
        port: <KUBERNETES-SERVICE-PORT>
        path: '<KUBERNETES-SERVICE-PATH>'

# Settings Descripts define user inputs and 
settings_descriptors:
  # list of descriptos
  - name: <DESCRIPTOR-NAME>
    display: '<A QUESTION TO ASK THE USER ON SIGN-UP>'
    input_type: string
    default: '<DEFAULT ANSWER>'
    components:
      - name: '<COMPONENT-NAME>' # Provide value to this componet 
        helm_set:
          - key: '<SET-KEY>'
```

{% endcode %}

### Creating Application Blueprint

To create an application blueprint archive the application manifest and helm charts into a blueprint tar.gz

```
$ tar -cf <BLUEPRINT-NAME> jovianx.yaml <HELM-CHART> ...
```

{% hint style="info" %}
Note: The Helm Charts should be open, untar direcotry.
{% endhint %}

Example: the following directory has an application manifest `jovianx.yaml` and a Chart `my-helm-chart`

```bash
├── my-helm-chart
│   ├── charts
│   ├── templates
│   ├── Chart.yaml
│   └── values.yaml
└── jovianx.yaml
```

To create an application blueprint for the directory use the following command:

```
$ tar -cf blueprint-1.0.0.tar.gz jovianx.yaml my-helm-chart
```

### Upload Application Blueprint

#### Upload Blueprint via Web UI

To upload your application blueprint to JovianX via the web console:

1. Navigate to Blueprints page
2. Click on `Upload a new Blueprint` bar
3. Click on `Choose blueprint tar.gz` file
4. Click on `Upload` to upload your blueprint

![](https://2226616041-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LdZQYW5C5jmCEGbhAlO%2F-Ln7AMk1GC8r-OiNam8T%2F-Ln7CKts1jDl-2Mh-nb3%2FScreenshot-20190825125210-1252x389.png?alt=media\&token=60ed648b-7569-4e8f-99ee-d0bb717d6af0)

Once the blueprint is upload you will be able to find it in the blueprints list, and view the application manifest.

#### Upload Blueprint via CURL(CI)

To upload your application blueprint to JovianX via an automated CI process or from command line, you will need to find your `API Access Key` and `API Secret`. You can find both in `Upload a new Blueprint` bar under `Blueprints` navigation bar.

```
curl -u '<ACCOUNT-API-ACCESS-KEY>:<API-SECRET>' -F 'file=@<PATH/TO/BLUEPRINT/FILE.TAR.GZ>' 'https://<ACCOUNT-API-PATH>/api/v1/upload_blueprint?make_default=true'
```

## Application Manifest (jovianx.yaml) Reference

## Application Manifest Root

| Key                                                                     | Description                                                                                                                                                                                                                                                                     |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jovianx_api_version`                                                   | <p><strong>Description</strong>: Version of the JovianX Manifest API.</p><p><strong>Parent</strong>: Root<br><strong>Type</strong>: v1</p><p><strong>Required</strong></p>                                                                                                      |
| `application_name`                                                      | <p><strong>Description</strong>: Name of the SaaS Application.</p><p><strong>Parent</strong>: Root<br><strong>Type</strong>: string</p><p><strong>Required</strong></p>                                                                                                         |
| `version`                                                               | <p><strong>Description</strong>: Version of the JovianX blueprint.</p><p><strong>Parent</strong>: Root<br><strong>Type</strong>: semantic version</p><p><strong>Required</strong></p>                                                                                           |
| `main_endpoint_component`                                               | <p><strong>Description</strong>: Main application end-point.</p><p><strong>Parent</strong>: Root<br><strong>Type</strong>: string</p><p><strong>Required</strong></p>                                                                                                           |
| [`components`](#components)                                             | <p><strong>Description</strong>: components section is a list of all components(Helm Charts or Cloud Managed Services) used as part of the application, and their settings.</p><p><strong>Parent</strong>: Root<br><strong>Type</strong>: list<br><strong>Required</strong></p> |
| `application_launch_timeout`                                            | <p><strong>Description</strong>: Application timeout configuration</p><p><strong>Parent</strong>: Root<br><strong>Type</strong>: collection</p><p><strong>Optional</strong></p>                                                                                                 |
| <p><code>status\_check:</code><br> <code>failure\_threshold:</code></p> | <p><strong>Description</strong>: How many status error detection are accepted before changing the app status to error.</p><p><strong>Parent</strong>: Root Type: collection</p><p><strong>Default</strong>: 1</p><p>Optional</p>                                                |
| `agents`                                                                | <p><strong>Description</strong>: The list of agents</p><p><strong>Parent</strong>: Root<br><strong>Type</strong>: list</p><p><strong>Optional</strong></p>                                                                                                                      |
| `settings_descriptors`                                                  | <p><strong>Description</strong>: A list of settings descriptors</p><p><strong>Parent</strong>: Root<br><strong>Type</strong>: list</p><p><strong>Optional</strong></p>                                                                                                          |
| `hooks`                                                                 | <p><strong>Description</strong>: List of hooks</p><p><strong>Parent</strong>: Root<br><strong>Type</strong>: list</p><p><strong>Optional</strong></p>                                                                                                                           |

## Components

Components section is a list of all components used as part of the application, and their settings. Components are Helm Charts or Cloud Managed Services.

| Key                | Description                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`             | <p><strong>Description</strong>: Name of the component</p><p><strong>Parent</strong>: components<br><strong>Type</strong>: string</p><p><strong>Example</strong>: <code>name: 'my-component'</code></p><p><strong>Required</strong></p>                                                                                                                                                     |
| `version`          | <p><strong>Description</strong>: Version of the component</p><p><strong>Parent</strong>: components<br><strong>Type</strong>: semantic\_version</p><p><strong>Example</strong>: <code>version: 14.5.2</code></p><p><strong>Required</strong></p>                                                                                                                                            |
| `provider`         | <p><strong>Description</strong>: Provider that implements the component</p><p><strong>Parent</strong>: components<br><strong>Type</strong>: Select<br><strong>Options</strong>:</p><ul><li>helm\_chart</li><li>\[Additional providers available in private alpha]</li></ul><p><strong>Example</strong>: <code>provider: helm\_chart</code></p><p><strong>Required</strong></p>              |
| `helm_chart_name`  | <p><strong>Description</strong>: Path to unarchived helm chart within the blueprint</p><p><strong>Parent</strong>: components<br><strong>Type</strong>: string</p><p><strong>Example</strong>: <code>helm\_chart\_name: /my-helm-chart/</code></p><p><strong>Required for</strong> <code>helm\_chart</code> provider</p>                                                                    |
| `helm_values_file` | <p><strong>Description</strong>: Path to values.yaml file for the component</p><p><strong>Parent</strong>: components<br><strong>Type</strong>: string</p><p><strong>Example</strong>: <code>helm\_values\_file: /my-helm-chart/my-values.yaml</code></p><p><strong>Optional for</strong> <code>helm\_chart</code> provider</p>                                                             |
| `helm_set`         | <p><strong>Description</strong>: List of helm set key and value pairs</p><p><strong>Parent</strong>: components<br><strong>Type</strong>: list</p><p><strong>Example</strong>:</p><p><code>helm\_set:</code></p><p> <code>- key: image</code></p><p> <code>value: registry.hub.docker.com/my-company/image</code></p><p><strong>Optional for</strong> <code>helm\_chart</code> provider</p> |

## Settings Descriptors

| Key                 | Description                                    |
| ------------------- | ---------------------------------------------- |
| `name`              | **Type**: string                               |
| `display`           | **Type**: string                               |
| `input_type`        | **value**: string \| number \| radio \| select |
| `default`           | **Type**: string                               |
| `description_title` | **Type**: string                               |
| `select_options`    | **Type**: list                                 |

## Hooks

| Key            | Description                                                                                                                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pre_install`  | <p><strong>Description</strong>: List hooks that are executed before app install</p><p><strong>Parent</strong>: <code>hooks</code><br><strong>Type</strong>: list</p><p><strong>Optional</strong></p>   |
| `post_install` | <p><strong>Description</strong>: List of hooks that are executed after app install</p><p><strong>Parent</strong>: <code>hooks</code><br><strong>Type</strong>: list</p><p><strong>Optional</strong></p> |

### Hook

| Key         | Description |
| ----------- | ----------- |
| name        |             |
| on\_failure |             |
| timeout     |             |
| provider    |             |
| image       |             |
| command     |             |
| args        |             |
| env         |             |

## Variables

### Account

```
{{ account://vendor_company }}
```

```
{{ account://end_company }}
```

```
{{ account://account_api_key }}
```

```
{{ account://admin_email }}
```

```
{{ account://admin_password }}
```

```
{{ account://api_host }}
```

```
{{ account://application_version}}
```

{% code title="example" %}

```
components:
  - name: node-component
    version: 1.0.0
    provider: helm_chart # helm_chart | docker
    helm_chart_name: node-chart
    helm_values_file: values-jovianx.yaml
    helm_set:
      - key: repository
        value: https://gitlab.com/jovianx-saas-platform/hello-world-app.git
      - key: replicas
        value: 1
      - key: vendor_company
        value: '{{ account://vendor_company }}'
      - key: end_company
        value: '{{ account://end_company }}'
      - key: account_api_key
        value: '{{ account://account_api_key }}'
      - key: admin_email
        value: '{{ account://admin_email }}'
      - key: admin_password
        value: '{{ account://admin_password }}'
      - key: api_host
        value: '{{ account://api_host }}'
```

{% endcode %}

### Application