Execution

This section details how to configure your Blocklet's execution environment. You can define the runtime engine, specify lifecycle scripts that run at key moments, and declare necessary environment variables. Blocklet Server uses these configurations to install, start, and manage your application.

Blocklets can be executed either directly on the host system using the engine property or within an isolated Docker container via the docker configuration.

Runtime Engine (engine)#

The engine field specifies the command used to start your Blocklet. This is the primary method for running Blocklets that don't require containerization. It can be a simple string for basic commands or a more detailed object for complex setups.

Property	Type	Description
platform	string	Optional. Specifies the target OS. Valid values: darwin, linux, windows, freebsd.
interpreter	string	The interpreter to use. Valid values: binary, node, blocklet. Defaults to node.
source	string | object	The engine source. Can be a string (e.g., 'node index.js') or an object specifying a dependency from a URL or a Blocklet Store.
args	string[]	An array of arguments to pass to the engine. Defaults to [].

Examples

A simple Node.js application:

A more explicit configuration using an object:

Docker Container (docker)#

For greater isolation and consistency, you can run your Blocklet inside a Docker container. If the docker field is present, the engine field is ignored.

Property	Type	Description
image	string	The name of the Docker image to use (e.g., nginx:latest). Cannot be used at the same time as dockerfile.
dockerfile	string	The path to a Dockerfile in your project to build the image. Cannot be used at the same time as image. The file path will be automatically included in the bundle.

Examples

Using a pre-built image from Docker Hub:

Using a local Dockerfile:

Lifecycle Scripts (scripts)#

The scripts field allows you to define commands that are executed at specific points in the Blocklet's lifecycle. These are useful for tasks like database migrations, dependency setup, or cleanup.

The following diagram illustrates when these scripts are executed:

Available Hooks

Hook	Description
dev	Command to run for local development.
preFlight	Runs before any installation or update steps.
preInstall	Runs before the Blocklet is installed.
postInstall	Runs after the Blocklet is successfully installed.
preStart	Runs before the main engine or docker process is started.
postStart	Runs after the main process has successfully started.
preStop	Runs before the Blocklet is stopped.
preUninstall	Runs before the Blocklet is uninstalled.
preConfig	Runs before the configuration interface is shown to the user.

Example

Environment Variables (environments)#

Define a list of environment variables your Blocklet needs to run. The Blocklet Server will prompt the user to provide values for these variables during installation and configuration. These values are then injected into the Blocklet's execution environment.

Property	Type	Description
name	string	Required. The name of the environment variable (e.g., API_KEY). Must not start with reserved prefixes like BLOCKLET_, COMPONENT_, or ABTNODE_.
description	string	Required. A user-friendly description of what this variable is for, which will be shown in the UI.
default	string	An optional default value for the variable. Cannot be used when secure is true.
required	boolean	If true, the user must provide a value. Defaults to false.
secure	boolean	If true, the value is treated as a secret and is not displayed in the UI after being set. Defaults to false.
validation	string	An optional regex string to validate the user's input.
shared	boolean	If true, this variable can be shared with child components. Defaults to true unless secure is true.

Example

Timeouts (timeout)#

You can configure timeouts for specific operations to prevent your Blocklet from getting stuck during startup or script execution.

Property	Type	Description
start	number	The time in seconds that Blocklet Server waits for the Blocklet to start before considering it failed. Range: 10-600. Default: 60.
script	number	The maximum time in seconds that any lifecycle script is allowed to run before being terminated. Range: 1-1800.

Example

You now have a complete understanding of how to configure your Blocklet's execution behavior. By combining engine or docker with scripts and environments, you can create robust and configurable applications.

After setting up how your Blocklet runs, the next step is to define how it communicates with the outside world. Proceed to the Networking section to learn about configuring interfaces, ports, and public URLs.