Getting Started

This guide will walk you through the essential steps to get your first Blocklet Server instance up and running. In just a few minutes, you'll go from installation to a fully functional server.

Prerequisites#

Before you begin, ensure you have Node.js installed on your system. Blocklet Server requires a specific version of Node.js to function correctly. Please refer to the engines field in the project's package.json for the exact version requirement.

Step 1: Install the Blocklet CLI#

The first step is to install the Blocklet Command Line Interface (CLI) globally using npm. This tool provides all the necessary commands to manage your server and blocklets.

Open your terminal and run the following command:

Install Blocklet CLI

npm install -g @blocklet/cli

Once the installation is complete, you can verify it by checking the version:

Verify Installation

blocklet --version

Step 2: Initialize Your Server#

Now that the CLI is installed, you need to create a configuration for your Blocklet Server. This is done using the server init command.

  1. Create a new directory for your server and navigate into it:

    Create Server Directory

    mkdir my-blocklet-server
cd my-blocklet-server
  2. Run the initialization command:

    Initialize Server

    blocklet server init

This command will launch an interactive setup wizard that guides you through the configuration process. You'll be asked for basic information such as the server's name, description, and port.

Interactive Setup Example

? Naming the server? my-node
? Description of the server? My first Blocklet Server instance
? Which port do you want your server to listen on? 3030
? Choose routing engine (Use arrow keys)
❯ nginx
  caddy
  none
...

Upon completion, a new .blocklet-server directory will be created, containing your config.yml file and other necessary server data.

Step 3: Start the Server#

With the configuration in place, you can now start the server. The server start command launches all necessary background processes, including the main daemon and services.

Start the Server

blocklet server start

After a few moments, the server will be running. The console will display the access URLs for your server's dashboard, which you can use to manage your server from a web browser.

Successful Start Output

...✅ Blocklet Server daemon started successfully!

ℹ Your Blocklet Server is running at the following URLs:
  - http://192.168.1.100/admin/
  - http://127.0.0.1/admin/

All-in-One Command#

For a faster setup, you can combine initialization and startup into a single command using the --auto-init flag. This is perfect for development or testing environments as it initializes the server with default settings and starts it immediately.

Auto-Initialize and Start

# Make sure you are in an empty directory
blocklet server start --auto-init

This command will automatically create the configuration with sensible defaults and proceed to start the server, printing the access URLs once it's ready.


Congratulations! Your Blocklet Server is now installed and running. You can now proceed to the Server Management section to learn how to stop, check the status, and further manage your instance.

Overview
Server Management