Manifest file

This section has the goal to present the manifest file and share some sample projects available in public repositories.

The manifest file is created automatically when creating a new Carol App (Online or Batch).

Sample file

Following a sample of the manifest file:

{
  "batch": {
    "processes": [{
      "algorithmDescription": {
        "en-US": "Batch task Description",
        "pt-BR": "Descrição do Tarefa Batch"
      },
      "algorithmName": "batch_carolapp_algorithm",
      "algorithmTitle": {
        "en-US": "Batch task Description",
        "pt-BR": "Descrição do Tarefa Batch"
      },
      "dataModels": [],
      "instanceProperties": {
        "properties": {
          "dockerName": "batch_carolapp-batch_carolapp_algorithm",
          "instanceType": "c1.nano",
          "preemptible": false
        }
      },
      "name": "batch_carolapp"
    }]
  },
  "online": {
    "processes": [{
      "algorithmDescription": {
        "en-US": "Online Description",
        "pt-BR": "Descrição do Online app"
      },
      "algorithmName": "online_app",
      "algorithmTitle": {
        "en-US": "Online Description",
        "pt-BR": "Descrição do Online app"
      },
      "instanceProperties": {
        "profile": "",
        "properties": {
          "instanceType": "c1.micro",
          "dockerImage": "online_app",
          "autoscale": {
            "enabled": true,
            "minReplicas": 1,
            "maxReplicas": 4
          },
          "healthcheck": {
            "path": "/healthy"
          },
          "port": 8080,
          "preemptible": true
        }
      },
      "name": "online_carolapp"
    }]
  },
  "docker": [{
    "dockerName": "batch_carolapp-batch_carolapp_algorithm",
    "dockerTag": "0.1.0",
    "gitBranch": "app_review",
    "gitPath": "/batch_carolapp",
    "gitDockerfileName": "Dockerfile",
    "gitRepoUrl": "https://github.com/totvslabs/carolapp-samples"
  }]
}

Understanding the manifest file

This section explain the most important properties in the manifest file.

PropertyDescription
batch/onlineThe same file can specify the configuration for both Batch and Online Carol App. It means that the Carol App supports both type of Carol App, including the Web resource, being deployed as a separate resource in Carol.
algorithmDescription/algorithmTitleBoth properties allow specifying information that will be available on the screen for the user operating the Carol App.

These properties support internationalization.
algorithmNameThis property specify the algorithm name responsible to initialize the execution of the Batch Carol App or Online Carol App.
instancePropertiesAllow specifying some custom properties for the Carol App.

Some predefined properties are described bellow (docker for example).
dataModelsSpecify the data models this process is looking for events (change, a new record or deleted records) to enable the next scheduled task.

If no event, the task will be created in Carol just to make it clear to the user that the schedule is working, but no instance and no process will run.
instanceProperties.properties.dockerNameThe property dockerName refers to the right docker instance below. Specifying all settings related to the docker, like tag, gitBranch, gitBranch, gitpath, instanceType, gitDockerfilename, gitRepoUrl**.
instanceProperties.properties.instanceTypeThis is the Instance Type to run the Carol App Process.
instanceProperties.preemptibleValue "true" specifies that the instance may die suddenly and "false" means that the instance is more robust (and expensive) and it will not die suddenly.

Normally Batch Apps are OK with preemptible as true, but we strongly recommend Online Apps as preemptible false.

The default value is "true".
nameThis is the identifier for the processes (online and batch) inside the manifest file.
dockerThis section describes all dockers used by this manifest file. The link happens through the dockerName tag.

This property specifies the following setting related to this docker image like tag, gitBranch, gitBranch, gitpath, gitRepoUrl.


This setting was added recently, after the deployment 3.7, but old manifest files without this property are still supported.
instanceProperties.properties.autoscaleThis block is available only for online apps, allowing to enable autoscaling (based on CPU usage), as well as the minimum and maximum replicas an online app should have.
instanceProperties.properties.autoscale.enabledWhether the app should be autoscaled or not. If enabled, it will scale the app up if the average CPU usage is above 75% for some time and down if it stays below that marker for a couple of minutes. Defaults to false.
instanceProperties.properties.autoscale.minReplicasMinimum replicas an app should have. Defaults to 1.
instanceProperties.properties.autoscale.maxReplicasMaximum replicas an app should have. Should be bigger than minReplicas and at most 5.
instanceProperties.properties.healthcheck.pathThe healthcheck block is available only for online apps, allowing to set a custom path for the app's health check. Defaults to /.
instanceProperties.properties.portCustomize the port in which the online app listens to. Defaults to 5000.
instanceProperties.properties.commandThe command to be run by the container. Equivalent to the ENTRYPOINT Docker property.
instanceProperties.properties.argsThe arguments passed to the command the container will run.
instanceProperties.properties.deadlineMax time a batch is allowed to run. Must be informed in the seconds, minutes or hours. For example: 40s, 15m, 1h. Hard limit is 24h.

📘

Instance Type

The following documentation share all possible instance types: https://docs.carol.ai/docs/carol-app-instance-type

📘

Specifying an external Docker Image

You can specify an external docker image name (URL) by replacing the properties "dockerName" in "instanceProperties"/"properties" by "dockerImage".

A complete example of this configuration is available here: https://github.com/totvslabs/carolapp-samples/blob/master/online-nodejs-carolapp/ai-script/manifest.json

Possible issues

If something goes wrong, you will see the following screen:

900900

The most common problem is specifying the version latest for pyCarol. It is mandatory to specify a version, as today (02-23-2020) the most recent and stable version is 2.30.0.