Execution & Environment

The execution and environment configuration within your blocklet.yml is the blueprint for how your Blocklet runs. It specifies the necessary runtime, defines system requirements, exposes configuration options to users, and hooks into the Blocklet's lifecycle. Getting this section right is crucial for creating a portable, robust, and user-friendly application.

This section covers five key areas: engine, docker, requirements, environments, scripts, and timeout.

Engine (engine)#

This property specifies the execution engine for your blocklet, defining the runtime and how it should be started. For most JavaScript-based blocklets, you'll specify node as the interpreter, and the main property (defined at the root of blocklet.yml) will serve as the entry point.

name: my-node-blocklet
main: build/index.js
engine:
  interpreter: node

You can also provide an array of engine configurations to support multiple platforms, which is ideal for binary distributions.

# ... other properties
engine:
  - platform: linux
    interpreter: binary
    source: ./bin/server-linux
  - platform: darwin
    interpreter: binary
    source: ./bin/server-macos
  - platform: win32
    interpreter: binary
    source: ./bin/server-win.exe

Engine Properties#

Docker (docker)#

As an alternative to the engine property, you can use docker to run your blocklet in a containerized environment. This is ideal for applications with complex dependencies or non-JavaScript runtimes. You must provide either an image or a dockerfile.

docker:
  image: 'nginx:latest'
  egress: true

When using a dockerfile, you must also include its path in the root files array.

docker:
  dockerfile: 'Dockerfile.prod'
files:
  - 'Dockerfile.prod'

Docker Properties#

Runtime Requirements (requirements)#

This object defines the environment constraints necessary for the blocklet to run correctly. The system will check these requirements before installation to ensure compatibility.

requirements:
  server: '>=1.16.0'
  os: '*'
  cpu: 'x64'
  nodejs: '>=18.0.0'

Requirement Properties#

Environment Variables (environments)#

The environments array allows you to define custom configuration variables. These are presented to the user during installation or on the blocklet's configuration page, allowing them to securely input API keys, set feature flags, or customize behavior.

environments:
  - name: 'API_KEY'
    description: 'Your secret API key for the external service.'
    required: true
    secure: true
  - name: 'FEATURE_FLAG_BETA'
    description: 'Enable the beta feature for this blocklet.'
    required: false
    default: 'false'
    validation: '^(true|false)$'

Key Naming Rules:

• Names must not start with the reserved prefixes BLOCKLET_, COMPONENT_, or ABTNODE_.
• Names can only contain letters, numbers, and underscores (_).

Environment Properties#

Lifecycle Scripts (scripts)#

Scripts are shell commands that hook into the blocklet's lifecycle, allowing you to perform automated tasks at specific stages like installation, startup, or uninstallation. The following diagram illustrates when the installation and startup hooks are executed:

scripts:
  pre-install: 'npm install --production'
  post-start: 'node ./scripts/post-start.js'
  pre-stop: 'echo "Shutting down..."'

Available Hooks#

Hook (kebab-case)	When It Runs
dev	The command to run the blocklet in development mode.
e2eDev	The command to run for end-to-end testing in a development environment.
pre-flight	Before the installation process begins, for initial checks.
pre-install	Before the blocklet files are copied to their final destination.
post-install	After the blocklet has been successfully installed.
pre-start	Before the blocklet's main process is started.
post-start	After the blocklet has successfully started.
pre-stop	Before the blocklet is stopped.
pre-uninstall	Before the blocklet is uninstalled.
pre-config	Before the configuration user interface is displayed to the user.

Timeouts (timeout)#

This object allows you to configure maximum wait times for critical lifecycle operations to prevent processes from hanging indefinitely.

timeout:
  start: 120  # Wait up to 120 seconds for the blocklet to start
  script: 600 # Allow scripts to run for up to 10 minutes

Timeout Properties#

With the execution environment configured, the next step is to define how your blocklet communicates with the outside world. Proceed to the Interfaces & Services section to learn how to expose web pages and API endpoints.