Kubos Applications Service ========================== The Kubos applications service is responsible for monitoring and managing all mission applications for a system. The service is capable of tracking multiple versions of each application, allowing users to easily upgrade and rollback their mission applications when necessary. .. todo:: TODO: User/App/Service interaction diagram Whenever a new application is registered with the service, its manifest file and all other files in the specified directory are copied into the service's application registry. By default, this registry is stored under `/home/system/kubos/apps`. .. uml:: @startuml frame "App Service" { package "Main Mission App" { rectangle [Version: 1.0\nActive: False] rectangle [Version: 2.0\nActive: True] } package "Payload App" { rectangle [Version: 0.1\nActive: False] } } @enduml Communicating with the Service ------------------------------ The applications service uses the same HTTP+GraphQL communication scheme as the :doc:`other services <../services/graphql>`. Users will send GraphQL queries and mutations to the service's HTTP listener port. The port number can be found in the system's :doc:`configuration file <../services/service-config>` in `/home/system/etc/config.toml` Querying -------- A current list of all available versions of all registered applications can be generated by using the ``apps`` query. For example:: { apps { active, app { name, version } } Using our example registry, the data returned by the service would be:: { "apps": [ { "active": false, "app": { "name": "main-mission", "version": "1.0" } }, { "active": false, "app": { "name": "main-mission", "version": "1.1" } }, { "active": true, "app": { "name": "main-mission", "version": "2.0" } }, { "active": true, "app": { "name": "payload-app", "version": "1.0" } }, ] } To list all available versions of a specific application, specify the app's name as an input parameter. For example:: { apps(name: "main-mission") { app { name, version } } } .. _register-app: Registering ----------- Once an application has been written and compiled, the application and its accompanying :ref:`manifest.toml file ` should be transferred to a new directory on the OBC. This file transfer can be done using the :doc:`file transfer service <../services/file>`. The application may be split into multiple files (which is useful for large Python apps), however, the name of the initial file which should be called for execution must exactly match the ``name`` property in the manifest file. It can then be registered with the applications service using the ``register`` mutation by specifying the directory containing the application files. The service will copy all of the contents from the specified path into the apps registry. Once registered, users may delete the original application files. For example:: mutation { register(path: "/home/kubos/payload-app") { success, errors, entry { active, app { name, version } } } } The ``success`` response field is a boolean value which reflects whether the registration process completed successfully. If ``true``, then the ``entry`` field will contain the registration information about the newly registered application. If ``false,`` then the ``entry`` field will be empty, and the ``errors`` field will contain an error message detailing what went wrong. De-Registering -------------- The ``uninstall`` mutation can be used to either uninstall a single version of an application, or to uninstall all versions of an application. The mutation takes one required argument, ``name``, specifying the name of the application to be removed. There is also one optional argument, ``version``, which specifies a particular version of the application which should be uninstalled. If ``version`` is omitted, then all known versions of the application are uninstalled. The mutation returns two fields: - ``success`` - Indicating the overall result of the uninstall operation - ``errors`` - Any errors which were encountered during the uninstall process For example:: mutation { uninstall(name: "main-mission", version: "1.1") { success, errors } } If the version of the application being uninstalled is also the current active version, the :ref:`setVersion ` mutation should be used in order to manually roll back to a prior version first. If the active version is not changed, then the system will not know which version to use the next time the application is started. .. _start-app: Starting an Application ----------------------- To manually start an application, the ``startApp`` mutation can be used. The mutation has two required arguments: the name of the application to start and the run level which the app should execute with. The optional ``args`` input argument allows additional arguments to be passed through to the underlying application. These arguments will be passed behind a ``--`` separator. The mutation will return three fields: - ``success`` - Indicating the overall result of the operation - ``errors`` - Any errors which were encountered while starting the application - ``pid`` - The PID of the started application. This will be empty if any errors are encountered For example:: mutation { startApp(name: "mission-app", runLevel: "OnCommand", args: ["-m", "safemode"]) { success, errors, pid } } Under the covers, the service receives the mutation and identifies the current active version of the application specified. It then calls that version's binary, passing along the run level as a command argument, as well as any additional arguments specified with ``args``. If the application immediately fails, the ``errors`` field will contain a message with the application's return code. Passing Additional Arguments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To pass additional arguments to the underlying application, the ``args`` input argument can be used. For example:: mutation { startApp(name: "mission-app", runLevel: "OnCommand", args: "--verbose --release") { success } } Under the covers, the application would be called like so:: mission-app -r OnCommand --verbose --release Automatically Starting on Boot ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ All applications will be started with the ``OnBoot`` run level automatically when the applications service is started during system initialization. This logic may also be triggered by manually starting the applications service with the ``-b`` flag. If an application cannot be started, or immediately fails, an error message will be written to the service's log with the failure reason. Upgrading --------- Users may register a new version of an application without needing to remove the existing registration. To do this, they will re-use the ``register`` mutation. However, the version number specified in the `manifest.toml` file must be unique. If an application with the specified name and version already exists, the registration will be rejected. :: mutation { register(path: "/home/kubos/payload-app") { active, app { name, version } } } .. _set-version: Changing Versions ----------------- Users may swap between different versions of an application by using the ``setVersion`` mutation. This is useful for manually rolling back to an older version of an application prior to uninstalling the current version. :: mutation { setVersion(name: "mission-app", version: "1.0") { success, errors } } Customizing the Applications Service ------------------------------------ The configuration for the applications service is saved in `/home/system/etc/config.toml`. This file can be editted to add or modify the following fields: - ``[app-service.addr]`` - ``ip`` - The IP address that the service will use - ``port`` - The port GraphQL requests should be sent to - ``[app-service]`` - ``registry-dir`` - *(Default: /home/system/kubos/apps)* The directory under which all registry entries should be stored