Finsemble boot sequence
Overview
A smart desktop consists of both apps (visible user interfaces) and services (invisible JavaScript processes that augment the smart desktop'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 Finsemble 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
Here are the 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 (such as window and workspace services). |
pre-authentication | The app services that need to perform some operations very early start at this stage. Note that no user has been authenticated yet, so there is no access to storage, preferences, workspaces or notifications. Don't use this stage unless you must. |
authentication | The user is authenticated. |
appd-retrieval | AppD records from configured AppD servers are retrieved. |
system-preuser | The stage for secondary Finsemble services. |
preuser | The default stage for app services. |
preuser2 | Extra optional stage for app services. |
preuser3 | Extra optional stage for app services. |
preuser4 | Extra optional stage for app services. |
earlyuser | The first tier apps are started (such as the Toolbar). |
user | All remaining apps are started. This is the default stage for auto-start apps. |
For more info about how to use boot stages, see App services.
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 smart desktop's boot sequence is the system log, which provides the history and current state of the startup process. If you set finsemble.bootConfig.onErrorMakeSystemManagerVisible to true, the system log displays automatically when a boot error occurs. Additionally, there are two other ways to make the
system log visible:
- Click System Log in the Finsemble menu.
- Set
startup_app.autoShowtotruein 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 app services to the boot sequence
When you add app services, you need to configure them by adding them to the boot sequence. See App services for details.
API reference
The primary way to control the boot sequence is via the smart desktop's configuration. See the Config Reference.
Common startup errors
If the smart desktop 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 timeout" | 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. It is also possible that your timeout value is too small. You can extend the timeout by changing the timeout value in the manifest. |