Deploy Blocklet

The blocklet deploy command pushes a blocklet from your local development environment directly to a running Blocklet Server instance. This is the primary method for distributing and testing your blocklets on a server.

This guide covers the main deployment scenarios, from testing on a local server to pushing to a remote production environment.

Prerequisites#

Before deploying, your blocklet must be packaged into a deployable bundle. This process collects all necessary assets and metadata. If you have not done so, please follow the Bundle Blocklet guide first.

Usage#

The basic syntax for the deploy command is:

• <directory>: The path to your blocklet project. It defaults to the current directory if omitted.

Deployment Scenarios#

There are two primary targets for deployment: a local server running on your machine or a remote server.

Deploying to a Local Server#

This is the most common scenario during development. It allows you to quickly test your bundled blocklet in a real server environment.

Requirements:

1. Blocklet Server must be running on your machine. You can start it with blocklet server start.
2. You need the DID of the target application on your server. For a standard local setup, this is often the DID of the Blocklet Server itself.

To deploy locally, run the command from your blocklet's root directory:

The CLI automatically detects the running server's port and creates temporary, single-use credentials for the deployment. You do not need to provide an endpoint or access keys.

Deploying to a Remote Server#

When you're ready to deploy to a staging or production server, you'll need to specify its endpoint. Authentication can be handled in two ways.

Method 1: Using Access Keys (For CI/CD)#

For automated environments like CI/CD pipelines, you can provide the server endpoint and access credentials as command-line arguments. This method is non-interactive.

Method 2: Using DID Connect (For Manual Deployment)#

For manual deployments from your local machine, you can omit the access key and secret. The CLI will initiate an interactive process to generate and store credentials securely.

When you run this for the first time, you will be prompted to open a URL in your browser. After authenticating with your wallet (e.g., DID Wallet), a new access key is generated and sent back to the CLI. These credentials are then saved locally for future deployments to the same application.

The interactive authentication flow works as follows:

Key Options#

Here are the most common options for the deploy command:

Option	Description	Required
[directory]	The path to the blocklet project directory. Defaults to the current directory.	No
--endpoint	The URL of the target Blocklet Server.	For Remote
--access-key	The access key ID for authentication.	For CI/CD
--access-secret	The access key secret for authentication.	For CI/CD
--app-id, --app-did	The DID of the target application on the server where the blocklet will be installed as a component.	Yes
--mount-point	A specific URL path for the blocklet (e.g., /my-blocklet). By default, a path is generated from the blocklet's title or name.	No
--incremental	Enables incremental deployment. The CLI compares file hashes with the server and uploads only new or changed files, speeding up deploys.	No

Deployment Process Overview#

The deploy command follows a series of steps to ensure a successful deployment.

After a successful deployment, you can manage your blocklet through the Blocklet Server dashboard. To distribute your blocklet more widely, see the guide on how to Upload to Store.