Skip to main content

Custom Applications Manifest

As explained in the brain apps section, the brain apps and services are a way to extend the functionality of the brain.

In this section we will learn how to register the apps in the system into the launcher.

Introduction​

Each application can be defined in what we call a manifest file. This file contains the metadata of the app and is used by the launcher to display the app in the UI. The manifest file is a JSON which in internally parsed by the launcher and automatically register each app and service as a systemd service.

The manifest file is located in the root directory of the farm-ng-user-[<your_username>] and is called manifest.json with the following basic structure:

{
   "services": {
        "example-service": {
            "name": "example-service",
            "type": "service",
            "exec_cmd": "/farm_ng_image/venv/bin/python3 example_service.py",
            "autostart": true
        },
   }
}

See next sections for a detailed description of each field and advanced usage to include multiple services and apps in the same manifest file.

Manifest file format​

The manifest file must be a valid JSON file that contains a services field with a list of services and apps to register in the system.

Each service or app is defined by a unique name and a set of fields that describe the service or app. For educational purposes, we will use the following example showing all the supported fields and values:

{
   "services": {
        "example-service": {
            "name": "example-service",
            "type": "service",
            "exec_cmd": "/farm_ng_image/venv/bin/python3 example_service.py",
            "args": [
                "--config",
                "/opt/farmng/config.json",
                "--port",
                "8042"
            ],
            "autostart": true,
            "app_route": "8042",
            "display_name": "Example Service"
        },
   }
}

Supported fields​

The following fields are supported for services:

  • name: The name of the service. This name must be unique and cannot be repeated in the same manifest file. It will be used as the name of the systemd service.
  • type: The type of the service. This field must be set to either:
    • app: An application which can be launched from the launcher.
    • service: A background service.
  • exec_cmd: The command to execute to start the service. Usually the absolute path to the executable and could include your own virtual environment.
  • args: Optional, list of arguments to pass to the executable.
  • autostart: Optional, whether the service should be restarted automatically when it exits. Default is false.
  • app_route: Optional, port where the service will serve the GUI when launching a web app.
  • display_name: Optional, name of the service to display in the launcher.
  • deps: Optional, a list of background services in the same manifest that must be started first.

Advanced usage​

The manifest file can support multiple services and apps in the same file. This is useful to group related services and apps together with a list of dependencies.

One example is the farm-ng-user-[<your_username>] manifest file which contains all the services and apps that are installed by default in the brain.

{
  "services": {
    "example-service": {
      "name": "example-service",
      "type": "service",
      "exec_cmd": "/farm_ng_image/venv/bin/python3 example_service.py",
      "autostart": true
    },
    "example-app": {
      "name": "example-app",
      "type": "app",
      "exec_cmd": "/farm_ng_image/venv/bin/python3 example_app.py",
      "deps": [
        "example-service"
      ],
      "app_route": "8042",
      "display_name": "Example App"
    }
  }
}

Troubleshooting​

A correctly formatted manifest.json is crucial for the successful loading of your application/service in the launcher backend. While adhering to best practices and thoroughly checking your manifest file is recommended to prevent errors, there are occasions when you might encounter issues with a malformed manifest file.

If your application does not appear on the launcher screen, you can utilize journalctl to debug potential issues with manifest.json. This approach helps in identifying specific error messages related to the manifest file processing.

To begin debugging, open a terminal window on the robot and execute the following command:

sudo -su adminfarmng journalctl -f --user-unit farmng-launcher-backend | grep -v INFO

This command filters the system logs in real-time, highlighting key phrases that typically indicate issues related to manifest.json. By examining the output, you can pinpoint the exact nature of the problem, such as type mismatches, JSON parsing errors, or invalid service types. This targeted approach significantly reduces the time and effort required for troubleshooting.

Remember, the correct structure and content of manifest.json are vital for the seamless operation of your application within the launcher environment. Regularly reviewing and validating your manifest file can prevent many common issues.