Finsemble Boot Sequence

Overview

A SmartDesktop consists of both apps (visible user interfaces) and services (invisible Javascript processes that augment the SmartDesktop's functionality), collectively termed modules. Modules can depend on other each other for their function, necessitating Finsemble launch each one in a particular order called the boot sequence. A special service called the startup manager coordinates this, allowing desktop assemblers to specify the dependencies of their modules via JSON configuration.

⚠️ While it's possible to use all the functionality described in this guide for apps, this is an advanced use case. The normal use case for the boot sequence is services.

Startup Stages

There are six stages to the boot sequence that desktop assemblers can register their modules to start with:

Event Description
microkernel The router, config, and logger services start.
kernel The core services start (e.g. window and workspace services).
authentication The user is authenticated.
preuser The default stage for custom services.
earlyuser The first tier apps are started (e.g. the Toolbar).
user All remaining apps are started. This is the default stage for auto-start apps.

Explicit Dependencies

💡 Most users can safely skip this section! Boot stages are usually sufficient!

Sometimes you may require two services to come up in the same boot stage, yet one service depends on the other for its function. In this case, you can use explicit dependencies to ensure that the services are started in the correct sequence within the same boot stage. If the startup manager determines there is no sequence that satisfies a module's dependencies (e.g., there is a circular dependency or a mismatch between stages), it will log an error (or stop entirely, depending on configuration). Here are some examples:

Scenario Success?
Module A starts in the earlyuser stage and depends on Module B which starts in the authentication stage. ✔️
Module A starts in the earlyuser stage and depends on Module B which starts in the user stage.
Module A and Module B both start in the authentication stage, and A depends on B. ✔️
Module A and Module B both start in the authentication stage, A depends on B and B depends on A.

The System Log

The best way to learn about and troubleshoot the SmartDesktop's boot sequence is the system log, which provides the history and current state of the startup process.

The system log will display automatically if a boot error occurs. Additionally, there are two other ways to make the system log visible:

  1. By clicking “System Log” in the Finsemble menu.
  2. By configuration, setting startup_app.autoShow to true in manifest-local.json.

The system log also displays a copy of every Finsemble notification dispatched, allowing notifications to be read for troubleshooting even if the notification service fails.

Adding to the Boot Sequence

Adding to or modifying the boot sequence is done with JSON configuration. Check out our tutorial on the subject.

API Reference

The primary way to control the boot sequence is via the SmartDesktop's configuration. Refer to the Config Reference.

Common Startup Errors

If the SmartDesktop encounters an error on startup, the system log will become visible and display the error. Here is a catalog of common errors and how to resolve them.

Error Message Resolution
"failed importing into finsemble config because of bad URL or illegal JSON" Check your config files for a syntax error. If that's not it, make sure all the URL's specified in your manifest are correct and accessible.
"Error in stage [some stage]: [some stage] illegal boot configuration "0: initializeDeepLinkingTask dependency "[a dependency]" is unknown in this stage or previous stages" The startup manager couldn't find the specified dependency. Either it doesn't exist (check the spelling), or it doesn't have the correct boot stage (i.e, the boot stage is too late).
"Error in stage "[some stage]": [some stage] circular dependency" Remove the circular dependency (the error message will highlight the exact services in the cycle).
"[some service] startup failed due to a time out" This indicates the service was started, but failed to come fully online before the timeout. Check the service for errors in the Central Logger. If there are no errors in Central Logger and you are developing locally, go to http://localhost:9090 and click on the service name to open the DevTools.